pi-maestro-flow 0.2.0

package/skills/manage-status/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: manage-status
+description: "Show project dashboard with progress and next steps Arguments: "
+allowed-tools: Read Bash Glob Grep
+---
+
+<purpose>
+Project dashboard: artifact progress, task counts, active work, next-step suggestions.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/status.md
+</required_reading>
+
+<context>
+$ARGUMENTS (no arguments required)
+
+**State files read:**
+- `.workflow/state.json` -- project-level state machine + artifact registry
+- `.workflow/roadmap.md` -- milestone and phase structure
+- `.workflow/scratch/*/plan.json` -- plan metadata (via artifact registry paths)
+- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses
+
+**Output boundary**: Read-only command. MUST NOT write any files. All output is displayed to the user via text.
+</context>
+
+<invariants>
+1. **Read-only** — MUST NOT write or modify any files; this is a pure display command
+2. **Graceful degradation** — missing roadmap.md, plan.json, or task files MUST NOT cause failure; display available data and note missing sections
+3. **State accuracy** — progress percentages MUST be calculated from actual task statuses, NEVER estimated or inferred
+4. **Wiki health optional** — wiki health score display MUST degrade gracefully if wiki is unavailable
+5. **Complete dashboard** — MUST include: milestone progress, phase status, task counts, active work, and next-step suggestions
+</invariants>
+
+<execution>
+Follow '~/.maestro/workflows/status.md' completely.
+
+Next-step decision table defined in workflow status.md Step 5.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Load → Render** (State loading → Dashboard display)
+- REQUIRED: `.workflow/` exists and `state.json` is readable (E001/E002 if not).
+- REQUIRED: Project state loaded with milestone and artifact registry.
+- BLOCKED if state.json missing or corrupt (E002).
+
+**GATE 2: Render → Route** (Dashboard → Next-step suggestions)
+- REQUIRED: Per-phase progress calculated from actual task statuses.
+- REQUIRED: Dashboard rendered with progress bars and status table.
+- BLOCKED if state parsing fails entirely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized -- run `/maestro-init` first | parse_input |
+| E002 | fatal | `state.json` missing or corrupt -- project state unrecoverable | parse_input |
+</error_codes>
+
+<success_criteria>
+- [ ] Project state loaded from `state.json`
+- [ ] Roadmap parsed with milestone/phase structure
+- [ ] Per-phase progress calculated (task counts, completion %)
+- [ ] Dashboard rendered with progress bars and status table
+- [ ] Active work section shows current phase details
+- [ ] Next steps suggested based on current state analysis
+- [ ] Wiki health score displayed (or graceful unavailable message)
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Phase needs analysis | `/maestro-analyze {phase}` |
+| Phase needs planning | `/maestro-plan {phase}` |
+| Phase needs execution | `/maestro-execute {phase}` |
+| Milestone ready for audit | `/maestro-milestone-audit` |
+| Issues need triage | `/manage-issue list` |
+</completion>

package/skills/manage-wiki/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: manage-wiki
+description: "Manage wiki graph — health, cleanup, search, stats Arguments: <subcommand: health|search|cleanup|stats|connect|digest> [query] [--fix] [--dry-run]"
+allowed-tools: Read Write Edit Bash Glob Grep AskUserQuestion
+---
+
+<purpose>
+Wiki graph management: health, search, cleanup, stats, connect, digest.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/wiki-manage.md
+</required_reading>
+
+<context>
+$ARGUMENTS — subcommand and optional flags.
+
+**Subcommands:**
+| Subcommand | Description |
+|-----------|-------------|
+| `health` | Health dashboard — score, broken links, orphans, hubs (default) |
+| `search <query>` | Interactive BM25 search with follow-up actions |
+| `cleanup` | Find and resolve orphans, broken links, stale entries |
+| `stats` | Graph statistics — type distribution, tag frequency, growth trends |
+| `connect` | Find and link hidden connections — orphan rescue, missing links, transitive gaps |
+| `digest [topic]` | Generate knowledge digest with theme clustering and gap analysis |
+| No args | Same as `health` |
+
+**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
+- `--format brief|full` — (digest) Output format
+- `--recent N` — (digest) Scope to N most recent entries
+- `--create-issues` — (digest) Create issues for identified knowledge gaps
+
+**Output boundary**: File writes MUST target `.workflow/wiki/`, `.workflow/knowhow/`, or `.workflow/issues/issues.jsonl` (when `--create-issues`) only. NEVER modify source code or files outside these paths. `--dry-run` overrides `--fix` — no writes when both are set.
+</context>
+
+<invariants>
+1. **Dry-run precedence** — `--dry-run` MUST override `--fix` when both are passed; preview only, no writes
+2. **Read-only by default** — without `--fix` or `--create-issues`, all subcommands MUST be read-only
+3. **Confirmation on fixes** — `--fix` MUST show preview of changes before applying; auto-apply only when explicitly set
+4. **Graph integrity** — `connect` MUST NOT create circular link chains; validate graph acyclicity for parent-child relationships
+5. **Threshold enforcement** — `--min-similarity` MUST be respected; NEVER suggest connections below the threshold
+6. **Subcommand isolation** — each subcommand routes to its own workflow file; NEVER cross-execute subcommand logic
+</invariants>
+
+<execution>
+**Subcommand routing:**
+- `health|search|cleanup|stats` → Follow `~/.maestro/workflows/wiki-manage.md` completely.
+- `connect` → Follow `~/.maestro/workflows/wiki-connect.md` completely (Stages 1-6).
+- `digest` → Follow `~/.maestro/workflows/wiki-digest.md` completely (Stages 1-8).
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Parse → Load** (Subcommand routing → Wiki data loading)
+- REQUIRED: Subcommand parsed and validated (health/search/cleanup/stats/connect/digest).
+- REQUIRED: `.workflow/` initialized (E001 if missing).
+- BLOCKED if E003 (invalid subcommand) or E001.
+
+**GATE 2: Load → Execute** (Wiki data → Subcommand execution)
+- REQUIRED: Wiki data loaded via `maestro wiki` CLI.
+- REQUIRED: At least one wiki entry exists (E002 if none).
+- BLOCKED if wiki data loading fails entirely.
+
+**GATE 3: Execute → Write** (For mutating operations: cleanup --fix, connect --fix, digest --create-issues)
+- REQUIRED: Preview of changes shown to user.
+- REQUIRED: `--dry-run` NOT set (overrides `--fix`).
+- BLOCKED if preview generation fails or user declines.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | `.workflow/` not initialized — run `/maestro-init` first | validate |
+| E002 | fatal | No wiki entries found — create content first | load |
+| E003 | error | Invalid subcommand | parse_input |
+| W001 | warning | Health score below 50 — graph needs attention | health |
+| W002 | warning | Orphan cleanup had partial failures | cleanup |
+</error_codes>
+
+<success_criteria>
+- [ ] Subcommand parsed (health/search/cleanup/stats/connect/digest)
+- [ ] Wiki data loaded via `maestro wiki` CLI
+- [ ] Results displayed in formatted output
+- [ ] If cleanup/connect --fix: issues resolved and delta reported
+- [ ] If digest: themes clustered, gaps identified, coverage heatmap generated
+- [ ] Next-step suggestions provided
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Health score < 50 | `/manage-wiki cleanup --fix` |
+| Orphan entries found | `/manage-wiki connect --fix` |
+| Knowledge gaps identified | `/manage-knowhow-capture` |
+| Want knowledge synthesis | `/manage-wiki digest` |
+</completion>

package/skills/odyssey-debug/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: odyssey-debug
+description: "Long-running debug cycle — archaeology, diagnosis, fix, confirmation, generalization, discovery, and knowledge persistence Arguments: <issue> [--template <name>] [--skip-fix] [--skip-generalize] [--auto] [-y] [-c] [--heartbeat]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<base>@~/.maestro/workflows/odyssey-base.md</base>
+
+<purpose>
+archaeology → explore → diagnose → fix & confirm → generalize → discover siblings → persist.
+Exhaustive iteration until root cause confirmed or INCONCLUSIVE.
+</purpose>
+
+<boundary>
+**In scope:** Single bug/issue full loop.
+**Out of scope:** Features → `/odyssey-planex` | Quality review → `/odyssey-review-test-fix` | UI → `/odyssey-ui` | Architecture → `/maestro-plan`
+
+**`--template <name>`:**
+
+| Template | Strategy | Use case |
+|----------|----------|----------|
+| `performance` | profiling → hot path → allocation → cache | Performance degradation |
+| `memory-leak` | heap snapshot → retention chain → lifecycle | Memory leaks |
+| `race-condition` | timeline → concurrent access → lock analysis | Race conditions |
+| `regression` | git bisect → diff analysis → boundary check | Regressions |
+| `crash` | stack trace → null chain → error propagation | Crashes / exceptions |
+</boundary>
+
+<context>
+$ARGUMENTS
+
+**Flags:** `--skip-fix` analysis-only | `--skip-generalize` quick fix | `--template <name>` | `--auto` no delegate confirmation | `-y` auto-confirm | `-c` resume | `--heartbeat` /loop heartbeat
+
+**Session**: `.workflow/scratch/{YYYYMMDD}-debug-odyssey-{slug}/`
+**Output**: `session.json` | `evidence.ndjson` | `explore.json` | `understanding.md`
+
+**session.json — debug-specific fields:**
+```json
+{ "issue": "", "diagnosis_retries": 0, "root_cause": null, "confirmation": null,
+  "patterns": [], "generalization_stats": null }
+```
+
+**evidence.ndjson phases:** `archaeology|explore|diagnosis|discovery|decision|self-iteration`
+- `archaeology`: `sha`, `author`, `date`, `message`, `relevance`
+- `explore`: `category` (call_chain|recent_change|error_gap|similar_pattern), `detail`
+- `diagnosis`: `hypothesis`, `result` (confirmed|disproved|inconclusive)
+- `discovery`: `file`, `line`, `classification` (safe|risk|bug), `action` (fix|issue|decision|skip)
+- `decision`: `question`, `options`, `context`, `status`, `resolution`
+- `self-iteration`: `stage`, `round`, `assessment`, `expansion`
+
+**explore.json**: `{call_chains, recent_changes, error_gaps, similar_patterns, cli_tool, timestamp}`
+
+**phase_goals[]:**
+
+| ID | Goal | done_when | phase | skip_when |
+|----|------|-----------|-------|-----------|
+| G1 | Root cause identified | phase=diagnosis result=confirmed | S_DIAGNOSE | — |
+| G2 | Explore context gathered | explore.json ≥1 category | S_EXPLORE | — |
+| G3 | Fix applied and confirmed | confirmation.overall == confirmed | S_CONFIRM | skip_fix |
+| G4 | Pattern generalized | patterns[] ≥1 entry | S_GENERALIZE | skip_generalize |
+| G5 | Discoveries triaged | all scan hits classified | S_DISCOVER | skip_generalize |
+| G6 | Learnings persisted | spec entries created OR none actionable | S_RECORD | — |
+
+**understanding.md — 9 sections:**
+1. Issue & Scope ← S_INTAKE | 2. Archaeology ← S_ARCHAEOLOGY | 3. Exploration ← S_EXPLORE
+4. Hypotheses ← S_DIAGNOSE | 5. Root Cause ← S_DIAGNOSE | 6. Fix & Confirmation ← S_FIX+S_CONFIRM
+7. Generalization ← S_GENERALIZE | 8. Discoveries ← S_DISCOVER | 9. Learnings ← S_RECORD
+
+**Knowledge Persistence categories (§9):**
+
+| Category | Content | Follow-up |
+|----------|---------|-----------|
+| Recurring root cause pattern | Type + triggers + fix + detection | `/spec-add debug` |
+| Non-obvious workaround | Problem + steps + why obvious fix fails | `/spec-add learning` |
+| Architecture boundary violation | Violation + correct boundary + verification | `/spec-add arch` |
+| Reusable generalization pattern | Signature + risk + fix template + scope | `/spec-add coding` |
+</context>
+
+<invariants>
+1. **Evidence append-only** — never delete or overwrite evidence.ndjson entries
+2. **Phase goal tracking** — mark goal done/failed before transition; no silent skips
+3. **Generalize is mandatory** — S_GENERALIZE and S_DISCOVER execute unless `skip_generalize == true`. "No findings" from prior phases, convergence signals, or context pressure are NOT valid reasons to skip. The phase itself determines whether patterns exist.
+</invariants>
+
+<self_iteration>
+Applies to: **S_ARCHAEOLOGY, S_EXPLORE, S_DIAGNOSE, S_GENERALIZE**. Logic in base.
+</self_iteration>
+
+<state_machine>
+
+<states>
+S_INTAKE → S_ARCHAEOLOGY → S_EXPLORE → S_DIAGNOSE → S_FIX → S_CONFIRM → S_GENERALIZE → S_DISCOVER → S_RECORD → END
+</states>
+
+<transitions>
+S_INTAKE → S_INTAKE       : -c + session found → A_RESUME_SESSION
+S_INTAKE → S_ARCHAEOLOGY  : issue parsed → A_INTAKE
+S_INTAKE → S_INTAKE       : no issue, no session → AskUserQuestion
+
+S_ARCHAEOLOGY → S_EXPLORE     : complete
+S_EXPLORE     → S_DIAGNOSE    : complete
+
+S_DIAGNOSE → S_FIX          : confirmed, !skip_fix
+S_DIAGNOSE → S_GENERALIZE   : confirmed, skip_fix, !skip_generalize
+S_DIAGNOSE → S_RECORD       : confirmed, skip_fix, skip_generalize
+S_DIAGNOSE → S_DIAGNOSE     : all hypotheses failed, retries < 3 → A_ESCALATE_DIAGNOSIS
+S_DIAGNOSE → S_RECORD       : retries >= 3 → INCONCLUSIVE
+
+S_FIX     → S_CONFIRM       : fix implemented
+S_CONFIRM → S_GENERALIZE    : confirmed, !skip_generalize
+S_CONFIRM → S_RECORD        : confirmed, skip_generalize
+S_CONFIRM → S_FIX           : needs_rework
+
+S_GENERALIZE → S_DISCOVER   : similar code found
+S_GENERALIZE → S_RECORD     : all 3 layers scanned with evidence, total_hits == 0
+
+S_DISCOVER → S_DIAGNOSE     : new bug → cross_phase_loops++
+S_DISCOVER → S_FIX          : same-pattern bug + fix_template, !skip_fix → cross_phase_loops++
+S_DISCOVER → S_RECORD       : remaining_actionable == 0
+S_DISCOVER → S_RECORD       : loops >= max_loops → log per-item reasons
+
+S_RECORD   → END            : complete
+</transitions>
+
+<actions>
+
+### A_INTAKE
+1. Parse arguments, generate slug, create SESSION_DIR
+2. `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + Grep keywords
+3. Derive `phase_goals[]` from flags
+4. Write `session.json` + `understanding.md` §1, emit Goal Prompt
+
+Commit: `"odyssey-debug({slug}): INTAKE — parse target and load context"`
+
+### A_RESUME_SESSION
+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.
+
+`maestro delegate --role analyze --mode analysis` (`run_in_background: true`):
+- PURPOSE: Review recent modifications related to {issue}
+- EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
+
+Update §2. Commit: `"odyssey-debug({slug}): ARCHAEOLOGY — git history analysis"`
+
+### A_EXPLORE
+Skip if no CLI tools (W006).
+
+`maestro delegate --role explore --mode analysis` (`run_in_background: true`):
+- PURPOSE: Call chains, recent changes, error gaps, similar patterns
+- EXPECTED: JSON {call_chains, recent_changes, error_gaps, similar_patterns}
+
+Write `explore.json` + evidence phase=explore. Update §3. Mark G2. Commit: `"odyssey-debug({slug}): EXPLORE — codebase exploration"`
+
+### A_DIAGNOSE
+1. Hypotheses from evidence, ranked [HIGH]/[MEDIUM]/[LOW] → §4
+2. Test each → evidence phase=diagnosis
+3. Ambiguity → evidence phase=decision; Normal: AskUserQuestion | `-y`: defer
+4. Confirmed → `session.json.root_cause` + §5. Mark G1.
+
+Commit: `"odyssey-debug({slug}): DIAGNOSE — root cause confirmed"`
+
+### A_ESCALATE_DIAGNOSIS
+`diagnosis_retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → AskUserQuestion | `-y` → INCONCLUSIVE → S_RECORD.
+
+### A_FIX
+1. Present root cause + proposed fix. Normal: AskUserQuestion | `-y`: auto proceed
+2. Implement fix, evidence phase=decision
+
+Commit: `"odyssey-debug({slug}): FIX — {summary}"`
+
+### A_CONFIRM
+1. Run covering tests
+2. `maestro delegate --role review --mode analysis` (`run_in_background: true`):
+   - EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk}
+3. `session.json.confirmation`: `{test_result, cli_review, overall: "confirmed|needs_rework"}`
+4. Update §6. `needs_rework` → S_FIX. `confirmed` → mark G3.
+
+Commit: `"odyssey-debug({slug}): CONFIRM — fix verified"`
+
+### A_GENERALIZE
+
+**MANDATORY — executes unless `skip_generalize == true`. Prior-phase convergence, "no findings," or context pressure are NOT valid skip reasons.**
+
+Pattern source: confirmed root cause + applied fix.
+
+**Step 1 — 3-layer pattern extraction:**
+
+| Layer | Method | Targets |
+|-------|--------|---------|
+| Syntax | Build regex from fix diff → Grep | Missing `await`, unchecked null, wrong comparison, identical error-handling gap |
+| Semantic | Understand anti-pattern that caused the bug → Agent scan | Same async-without-catch, same boundary assumption, race on shared state |
+| Structural | Find files with same module shape / import graph | Sibling handlers, parallel service implementations, same-shape error handlers |
+
+Write `session.json.patterns[]`: `[{id, source, layer, signature, description, risk, fix_template, confidence}]`
+
+**Thoroughness floor:** ALL 3 layers must be attempted and logged. Each layer records search method, scope, hit count in evidence phase=generalization. "No hits" requires all 3 layers to return 0 with logged evidence — a single-layer quick grep does NOT satisfy.
+
+**Step 2 — 4-agent concurrent scan** (single message, 4 Agents):
+
+| Agent | Strategy | Scope |
+|-------|----------|-------|
+| Syntax grep | Grep regex from pattern signatures | Full project |
+| Semantic scan | Anti-pattern understanding → scan same bug class | Related modules |
+| Structural match | Find structurally similar files to buggy file | Full project |
+| Historical grep | `git log -S` for pattern signatures | Git history |
+
+**Step 3 — Cross-layer dedup:** multi-layer hit → boost | single-layer → `needs_review` | historically fixed → `regression_risk`
+
+**Step 4 — Iterative deepening:** Module with ≥3 hits → targeted deep scan (max 1 round).
+
+**Step 5 — Persist:** Update understanding.md §7 + write `session.json.generalization_stats`:
+```json
+{"patterns_extracted": 0, "total_hits": 0, "cross_layer_confirmed": 0, "regression_risks": 0, "by_layer": {"syntax": 0, "semantic": 0, "structural": 0}, "deepening_triggered": false}
+```
+
+**Transition guard:** `S_GENERALIZE → S_RECORD` requires `by_layer` has entries for all 3 layers with search evidence logged. Mark G4 done.
+
+Commit: `"odyssey-debug({slug}): GENERALIZE — pattern scan complete"`
+
+### A_DISCOVER
+
+**Executes whenever `total_hits > 0`. Cannot be skipped without `skip_generalize == true`.**
+
+1. **Triage** each hit with ±10 lines context → classify:
+   - `bug` — same defect pattern confirmed
+   - `risk` — potential issue needing guard
+   - `safe` — false positive (must log individual reason — blanket "pre-existing" forbidden)
+
+2. **Route:**
+
+   | Classification | Action |
+   |---------------|--------|
+   | bug + fix_template applicable | Immediate fix → back to S_FIX |
+   | bug + cross-module or no template | Create issue (fix suggestion + impact) |
+   | risk + guard addable directly | Fix directly |
+   | risk + complex | Create issue |
+   | safe | Skip with logged per-item reason |
+
+   Normal: AskUserQuestion per hit | `-y`: auto-fix bugs with fix_template, create issue for rest
+
+3. **Cross-phase loops:** `cross_phase_loops++` on fix/diagnose return. `loops >= max_loops` → must log per-item reasons.
+
+4. Append evidence phase=discovery. Update understanding.md §8. Mark G5 done.
+
+Commit: `"odyssey-debug({slug}): DISCOVER — sibling triage complete"`
+
+### A_RECORD
+
+1. Finalize understanding.md §9 — learnings by Knowledge Persistence categories:
+   - Recurring root cause pattern → `/spec-add debug`
+   - Non-obvious workaround → `/spec-add learning`
+   - Architecture boundary violation → `/spec-add arch`
+   - Reusable generalization pattern → `/spec-add coding`
+
+2. Mark G6 done. Pending decisions: Normal → AskUserQuestion | `-y` → skip (show deferred count).
+
+3. **Goal audit (hardened):**
+   - `done` → confirmed
+   - `skipped` → confirmed ONLY if corresponding `skip_when` flag is true
+   - **Hard rule:** G4 and G5 CANNOT be `skipped` unless `skip_generalize == true`. Pending without flag → `failed` (Normal: AskUserQuestion | `-y`: record `failed`)
+   - `phase_goals_all_done = true` only when all goals pass this audit
+
+4. `current_state = "COMPLETED"`, emit completion summary.
+
+**Completion summary:**
+```
+--- DEBUG ODYSSEY COMPLETE ---
+Issue:      {issue}
+Root cause: {root_cause.hypothesis}
+Fix:        {applied|skipped|inconclusive}
+Patterns:   {patterns_extracted} ({by_layer})
+Scan hits:  {total_hits} ({cross_layer_confirmed} confirmed)
+Issues:     {N} created
+Decisions:  {N} resolved, {M} pending, {K} deferred
+Learnings:  {N} persisted
+Self-iter:  {N} rounds across {M} stages
+Goals:      {done}/{total} ({skipped} skipped)
+---
+```
+
+Commit: `"odyssey-debug({slug}): RECORD — summary and knowledge persistence"`
+
+</actions>
+
+<appendix>
+
+### `-y` debug-specific points
+
+| Decision Point | Normal | `-y` |
+|---------------|--------|------|
+| A_DIAGNOSE ambiguity | AskUserQuestion | deferred |
+| A_ESCALATE 3-strike | AskUserQuestion | INCONCLUSIVE |
+| A_FIX direction | AskUserQuestion | auto proceed |
+| A_DISCOVER hit routing | AskUserQuestion | auto-fix bugs with template, create issue for rest |
+
+### Goal Prompt convergence rules
+
+```
+Stop when root cause confirmed (or INCONCLUSIVE), fix verified,
+generalization exhausted, phase_goals_all_done=true.
+All sibling bugs fixed or issued — no leftovers.
+```
+
+</appendix>
+
+</state_machine>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| 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 |
+| W007 | warning | Generalization 0 hits after full 3-layer scan | Advance to S_RECORD (requires all 3 layers attempted with evidence) |
+</error_codes>
+
+<success_criteria>
+- [ ] Session + 4 output files + prior knowledge searched
+- [ ] Archaeology + CLI review → evidence phase=archaeology
+- [ ] CLI exploration → explore.json + evidence phase=explore
+- [ ] Hypotheses tested, root cause with evidence refs
+- [ ] understanding.md 9 sections progressive
+- [ ] Fix + confirmed (unless --skip-fix)
+- [ ] Generalization + scan (unless --skip-generalize)
+- [ ] Discoveries classified; unfixed findings individually justified
+- [ ] phase_goals + goal audit + resumable via -c
+- [ ] Completion summary
+</success_criteria>
+
+<next_step_routing>
+| Condition | Next |
+|-----------|------|
+| Discovery issues | `/manage-issue list --source debug-odyssey` |
+| Document pattern | `/learn-decompose <module>` |
+| Formal review | `/quality-review <phase>` |
+| Second opinion | `/learn-second-opinion <understanding.md>` |
+| Related question | `/learn-investigate "<question>"` |
+| Pending decisions | Filter evidence phase=decision status=pending |
+</next_step_routing>