maestro-flow-one 0.1.0

package/codex/maestro-flow/chains/templates.json

@@ -0,0 +1,256 @@
+{
+  "version": "2.0",
+  "decision_types": {
+    "post-verify": {
+      "evaluates": "verification.json",
+      "verdict_prompt": "评估验证结果: passed/failed 状态, gaps 严重性",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-verify"]
+    },
+    "post-review": {
+      "evaluates": "review.json",
+      "verdict_prompt": "评估代码审查结果: verdict PASS/WARN/BLOCK",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "quality-review", "decision:post-review"]
+    },
+    "post-test": {
+      "evaluates": "uat.md, test-results.json",
+      "verdict_prompt": "评估测试结果: 通过率, 失败用例严重性",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-verify", "quality-test", "decision:post-test"]
+    },
+    "post-business-test": {
+      "evaluates": "business-test-results.json",
+      "verdict_prompt": "评估业务测试结果: 需求覆盖率, 失败场景",
+      "fix_loop": ["quality-debug", "maestro-plan --gaps", "maestro-execute", "maestro-verify", "decision:post-verify", "quality-auto-test", "decision:post-business-test"]
+    },
+    "post-milestone": {
+      "evaluates": "state.json",
+      "verdict_prompt": "检查是否有下一个 milestone",
+      "structural": true
+    }
+  },
+  "templates": {
+    "quick-fix": {
+      "description": "Diagnose and fix a known bug",
+      "category": "quick-fix",
+      "triggers": ["fix", "debug", "bug", "error", "crash", "broken"],
+      "steps": [
+        { "cmd": "quality-debug", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "maestro-plan", "args": "{phase} --gaps", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "issue-fix": {
+      "description": "Analyze, plan, fix, and close a tracked issue",
+      "category": "quick-fix",
+      "triggers": ["issue", "ISS-", "ticket"],
+      "steps": [
+        { "cmd": "maestro-analyze", "args": "--gaps {issue_id}", "type": "external" },
+        { "cmd": "maestro-plan", "args": "--gaps", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "manage-issue", "args": "close {issue_id} --resolution fixed", "type": "internal" }
+      ]
+    },
+    "analyze-plan-execute": {
+      "description": "Fast track: analyze, plan, and implement",
+      "category": "feature-build",
+      "triggers": ["implement", "build", "create", "develop", "add feature"],
+      "steps": [
+        { "cmd": "maestro-analyze", "args": "\"{intent}\"", "type": "external" },
+        { "cmd": "maestro-plan", "args": "--dir {scratch_dir}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "--dir {scratch_dir}", "type": "external" }
+      ]
+    },
+    "plan-execute-verify": {
+      "description": "Full phase: plan, execute, verify with quality gate",
+      "category": "feature-build",
+      "triggers": ["plan and execute", "phase", "plan execute"],
+      "steps": [
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "execute-verify": {
+      "description": "Execute existing plan and verify",
+      "category": "feature-build",
+      "triggers": ["execute", "run plan", "implement plan"],
+      "steps": [
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" }
+      ]
+    },
+    "quality-loop": {
+      "description": "Full quality check: verify, review, test with decision gates",
+      "category": "quality-check",
+      "triggers": ["check quality", "review and test", "quality", "qa"],
+      "steps": [
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-auto-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "quality-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-test", "args": "", "type": "decision", "decision": "post-test", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "review-fix": {
+      "description": "Fix review-blocked issues",
+      "category": "quality-check",
+      "triggers": ["fix review", "review block", "review fail"],
+      "steps": [
+        { "cmd": "maestro-plan", "args": "{phase} --gaps", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "brainstorm-driven": {
+      "description": "Explore idea then plan and build",
+      "category": "explore",
+      "triggers": ["brainstorm", "explore idea", "ideate"],
+      "steps": [
+        { "cmd": "maestro-brainstorm", "args": "\"{intent}\"", "type": "external" },
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "roadmap-driven": {
+      "description": "From requirements to roadmap to first phase with gates",
+      "category": "lifecycle",
+      "triggers": ["roadmap", "from requirements", "start project", "new project"],
+      "steps": [
+        { "cmd": "maestro-init", "args": "", "type": "internal" },
+        { "cmd": "maestro-roadmap", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "maestro-analyze", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 }
+      ]
+    },
+    "full-lifecycle": {
+      "description": "Complete phase lifecycle with all quality gates (ralph-equivalent)",
+      "category": "lifecycle",
+      "triggers": ["full lifecycle", "complete phase", "lifecycle", "ralph"],
+      "steps": [
+        { "cmd": "maestro-analyze", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-auto-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-business-test", "args": "", "type": "decision", "decision": "post-business-test", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-auto-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "quality-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-test", "args": "", "type": "decision", "decision": "post-test", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" },
+        { "cmd": "maestro-milestone-complete", "args": "", "type": "internal" },
+        { "cmd": "decision:post-milestone", "args": "", "type": "decision", "decision": "post-milestone" }
+      ]
+    },
+    "standard-lifecycle": {
+      "description": "Standard phase lifecycle: verify + review + test gates",
+      "category": "lifecycle",
+      "triggers": ["standard lifecycle", "standard phase", "standard"],
+      "steps": [
+        { "cmd": "maestro-plan", "args": "{phase}", "type": "internal" },
+        { "cmd": "maestro-execute", "args": "{phase}", "type": "external" },
+        { "cmd": "maestro-verify", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-verify", "args": "", "type": "decision", "decision": "post-verify", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-review", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-review", "args": "", "type": "decision", "decision": "post-review", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "quality-test", "args": "{phase}", "type": "internal" },
+        { "cmd": "decision:post-test", "args": "", "type": "decision", "decision": "post-test", "retry_count": 0, "max_retries": 2 },
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" }
+      ]
+    },
+    "milestone-close": {
+      "description": "Audit and close current milestone",
+      "category": "milestone",
+      "triggers": ["close milestone", "complete milestone", "milestone done"],
+      "steps": [
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" },
+        { "cmd": "maestro-milestone-complete", "args": "", "type": "internal" },
+        { "cmd": "decision:post-milestone", "args": "", "type": "decision", "decision": "post-milestone" }
+      ]
+    },
+    "milestone-release": {
+      "description": "Audit and release milestone with version tag",
+      "category": "milestone",
+      "triggers": ["release", "publish", "tag version", "ship"],
+      "steps": [
+        { "cmd": "maestro-milestone-audit", "args": "", "type": "internal" },
+        { "cmd": "maestro-milestone-release", "args": "", "type": "internal" }
+      ]
+    },
+    "learn-deep": {
+      "description": "Deep module understanding: read, decompose, critique",
+      "category": "explore",
+      "triggers": ["understand", "deep learn", "study", "learn module"],
+      "steps": [
+        { "cmd": "learn-follow", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "learn-decompose", "args": "\"{intent}\"", "type": "internal" },
+        { "cmd": "learn-second-opinion", "args": "\"{intent}\" --mode challenge", "type": "internal" }
+      ]
+    }
+  },
+  "single_commands": {
+    "status": "manage-status",
+    "init": "maestro-init",
+    "analyze": "maestro-analyze",
+    "plan": "maestro-plan",
+    "execute": "maestro-execute",
+    "verify": "maestro-verify",
+    "review": "quality-review",
+    "test": "quality-test",
+    "auto-test": "quality-auto-test",
+    "debug": "quality-debug",
+    "refactor": "quality-refactor",
+    "sync": "quality-sync",
+    "retrospective": "quality-retrospective",
+    "issue": "manage-issue",
+    "discover-issues": "manage-issue-discover",
+    "harvest": "manage-harvest",
+    "knowhow": "manage-knowhow",
+    "knowhow-capture": "manage-knowhow-capture",
+    "spec-add": "spec-add",
+    "spec-load": "spec-load",
+    "spec-remove": "spec-remove",
+    "spec-setup": "spec-setup",
+    "wiki": "manage-wiki",
+    "wiki-connect": "wiki-connect",
+    "wiki-digest": "wiki-digest",
+    "brainstorm": "maestro-brainstorm",
+    "roadmap": "maestro-roadmap",
+    "fork": "maestro-fork",
+    "merge": "maestro-merge",
+    "quick": "maestro-quick",
+    "learn-follow": "learn-follow",
+    "learn-investigate": "learn-investigate",
+    "learn-decompose": "learn-decompose",
+    "learn-retro": "learn-retro",
+    "learn-second-opinion": "learn-second-opinion",
+    "amend": "maestro-amend",
+    "compose": "maestro-composer",
+    "play": "maestro-player",
+    "update": "maestro-update",
+    "ui-design": "maestro-ui-design",
+    "milestone-audit": "maestro-milestone-audit",
+    "milestone-complete": "maestro-milestone-complete",
+    "milestone-release": "maestro-milestone-release",
+    "codebase-rebuild": "manage-codebase-rebuild",
+    "codebase-refresh": "manage-codebase-refresh"
+  }
+}

package/codex/maestro-flow/commands/learn/decompose.md

@@ -0,0 +1,113 @@
+---
+name: learn-decompose
+description: 4-dimension parallel pattern extraction via CSV wave pipeline. Structural, behavioral, data, and error dimension agents scan in parallel (Wave 1), cross-reference agent deduplicates and catalogs (Wave 2). Outputs pattern catalog to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency 4] [--continue] \"<path|module> [--patterns <list>] [--save-spec] [--save-wiki]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
+scan a module, then a cross-reference agent deduplicates against existing patterns and
+produces a catalog. Discovered patterns persist to `lessons.jsonl` and optionally to
+specs (via `spec-add`) and wiki.
+
+```
+Resolve Target → Load Existing Patterns → Wave 1 (4 parallel dimension scans) → Wave 2 (cross-ref + catalog) → Persist
+```
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution:**
+- File path → analyze that file
+- Directory path → all source files in it
+- Module name → Glob `src/**/{module}*`
+
+**Flags:**
+- `-y, --yes`: Skip confirmations
+- `-c, --concurrency N`: Max concurrent agents (default: 4)
+- `--continue`: Resume existing session
+- `--patterns <list>`: Comma-separated pattern names to focus on
+- `--save-spec`: Invoke `spec-add` for each new pattern
+- `--save-wiki`: Create wiki note entries per dimension group
+
+**Output**: `.workflow/.csv-wave/{session-id}/` + `.workflow/learning/decompose-{slug}-{date}.md`
+</context>
+
+<invariants>
+1. **4 dimensions always**: structural, behavioral, data, error — each a wave 1 task
+2. **Evidence required**: Every finding must have file:line anchors
+3. **Dedup before persist**: Cross-reference against existing specs + lessons
+4. **Stable IDs**: INS-id from `hash("decompose" + target + pattern_name)`
+5. **No files modified outside** `.workflow/learning/` (and optionally specs/wiki)
+</invariants>
+
+<execution>
+
+### Phase 1: Session Init + Target Resolution
+
+Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
+Extract remaining text as target path/module.
+
+Resolve target to file list. Load existing patterns from `coding-conventions.md` + `lessons.jsonl` for dedup set.
+
+### Phase 2: Wave 1 — Parallel Dimension Scans
+
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
+
+| id | dimension | focus |
+|----|-----------|-------|
+| 1 | structural | Class hierarchy, composition, DI, factories, exports |
+| 2 | behavioral | Events, middleware, observer, command, state machines |
+| 3 | data | Repository, DTO, caching, serialization, validation |
+| 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
+| 5 | cross-ref | Dedup + catalog from wave 1 findings |
+
+Each dimension agent returns:
+```json
+[{
+  "name": "pattern name",
+  "dimension": "structural|behavioral|data|error",
+  "confidence": "high|medium|low",
+  "anchors": ["file:line"],
+  "description": "what it does",
+  "rationale": "why this approach",
+  "tradeoffs": "what was given up"
+}]
+```
+
+### Phase 3: Wave 2 — Cross-Reference + Catalog
+
+Single agent receives all wave 1 findings via `prev_context`. 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
+
+### Phase 4: Persist
+
+1. Write `decompose-{slug}-{date}.md` with full catalog
+2. Append each **new** pattern to `lessons.jsonl` (source: "decompose", category: "pattern")
+3. If `--save-spec`: invoke `spec-add` per new pattern
+4. If `--save-wiki`: create wiki note per dimension group
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| 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 |
+| W002 | warning | coding-conventions.md not found | All patterns marked "new" |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete file list
+- [ ] 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)
+- [ ] Pattern catalog written to `decompose-{slug}-{date}.md`
+- [ ] New patterns appended to `lessons.jsonl` with stable INS-ids
+- [ ] If --save-spec / --save-wiki: entries created
+</success_criteria>

package/codex/maestro-flow/commands/learn/follow.md

@@ -0,0 +1,83 @@
+---
+name: learn-follow
+description: Guided follow-along reading of code or wiki entries. Section-by-section walk-through with 4 forcing questions, pattern extraction, and understanding map generation. Persists insights to lessons.jsonl.
+argument-hint: "<path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Guided reading experience for code files, wiki entries, or topics. Walks through content
+section by section using 4 forcing questions to extract patterns, identify assumptions,
+and build a structured understanding map. Insights persist to `lessons.jsonl`.
+
+Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
+deep reading that builds understanding incrementally.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution (auto-detected):**
+- File path → Read source file
+- Wiki ID (`type-slug`) → Fetch via `maestro wiki get`
+- Topic string → Search via `maestro wiki search`, use top result
+
+**Flags:**
+- `--depth shallow` — Key patterns and structure only (default)
+- `--depth deep` — Every function, branch, assumption
+- `--save-wiki` — Create wiki note with reading notes
+
+**Output**: `.workflow/learning/follow-{slug}-{date}.md`
+</context>
+
+<execution>
+
+### Stage 1: Resolve Target + Load Context Web
+- File: verify exists, parse imports for dependency files
+- Wiki ID: fetch + load forward/backlinks
+- Topic: search wiki, take top result
+- Build 1-hop context neighborhood (imports/exports or wiki links)
+
+### Stage 2: Build Reading Order
+- Single file: split into logical sections (function/class boundaries)
+- Directory: entry point → core modules → utilities → tests
+- `--depth shallow`: top-level structure only
+- `--depth deep`: every function body, every branch
+
+### Stage 3: Guided Reading (4 Forcing Questions per Section)
+1. **"What pattern is being used here?"** — design patterns, idioms, conventions
+2. **"Why this approach instead of alternatives?"** — trade-offs made
+3. **"What assumption does this depend on?"** — external state, input shape, ordering
+4. **"What would break if this changed?"** — fragility, downstream effects
+
+### Stage 4: Extract Patterns + Produce Understanding Map
+From forcing question answers, extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+
+Cross-reference against `coding-conventions.md`: documented vs undocumented patterns.
+
+### Stage 5: Persist
+1. Write `follow-{slug}-{date}.md` with understanding map
+2. Append new patterns to `lessons.jsonl` (source: "follow", stable INS-ids)
+3. If `--save-wiki`: create wiki note entry
+
+**Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Target not resolvable | Check path/ID or rephrase topic |
+| W001 | warning | Wiki graph unavailable | Proceed with code-only context |
+| W002 | warning | coding-conventions.md not found | Patterns flagged "unknown status" |
+| W003 | warning | Large target (>1000 lines) | Auto-switch to shallow depth |
+</error_codes>
+
+<success_criteria>
+- [ ] Target resolved to concrete content
+- [ ] Context web loaded (imports/exports or wiki links)
+- [ ] All 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors
+- [ ] Understanding map produced with concepts, patterns, assumptions, questions
+- [ ] `follow-{slug}-{date}.md` written
+- [ ] `lessons.jsonl` appended with stable INS-ids
+</success_criteria>

package/codex/maestro-flow/commands/learn/investigate.md

@@ -0,0 +1,83 @@
+---
+name: learn-investigate
+description: Systematic question investigation with hypothesis testing, evidence logging, and 3-strike escalation. 4-phase pipeline — evidence collection, pattern matching, hypothesis testing, synthesis. Persists findings to lessons.jsonl.
+argument-hint: "<question> [--scope <path>] [--max-hypotheses N]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Systematic investigation for understanding questions (not bug-fixing). 4-phase approach
+with scope lock and 3-strike escalation. Produces structured evidence trails and
+understanding documents that persist to the learning system.
+
+Unlike `quality-debug` (fixing bugs during execution), this answers "how does X work?",
+"why does Y happen?", "what would happen if Z?" questions.
+</purpose>
+
+<context>
+$ARGUMENTS — question text and optional flags.
+
+**Flags:**
+- `--scope <path>` — Restrict to files under this directory (default: entire project)
+- `--max-hypotheses N` — Max hypotheses before escalating (default: 3)
+
+**Output**: `.workflow/learning/investigate-{slug}/` (evidence.ndjson, understanding.md, report.md)
+</context>
+
+<execution>
+
+### Stage 1: Frame the Question
+- Parse question, generate slug, create investigation directory
+- Search prior knowledge: wiki search, grep lessons.jsonl, read debug-notes.md
+- Write initial `understanding.md`
+
+### Stage 2: Evidence Collection
+1. **Code search**: Grep keywords across scoped files
+2. **File inspection**: Read most relevant files
+3. **Import tracing**: Follow dependency chain
+4. **Git history**: `git log --oneline -10 -- <relevant-files>`
+
+Each evidence item → `evidence.ndjson`:
+```json
+{"ts":"ISO","type":"code|git|search|doc","source":"file:line","relevance":"high|medium|low","content":"...","note":"..."}
+```
+
+### Stage 3: Hypothesis Formation + Testing
+Generate ranked hypotheses from evidence. For each (in rank order):
+1. Design test: what evidence would confirm/disprove?
+2. Execute test: code trace, targeted search, experiment
+3. Record result in `evidence.ndjson` (type: "test")
+4. Update `understanding.md`: confirmed / disproved / inconclusive
+
+### Stage 4: 3-Strike Escalation
+If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark INCONCLUSIVE.
+
+### Stage 5: Synthesize + Persist
+1. Write `report.md` with answer, evidence trail, hypothesis results
+2. Append to `lessons.jsonl`:
+   - Confirmed → category: "technique" / "pattern"
+   - Disproved → category: "gotcha"
+3. Display summary with next-step routing
+
+**Next steps:** `/spec-add debug <finding>`, `/learn-follow <path>`, `/learn-decompose <module>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No question provided | Provide question as first argument |
+| E002 | error | Scope path does not exist | Check --scope path |
+| W001 | warning | No prior knowledge found | Proceed with fresh investigation |
+| W002 | warning | Very few evidence matches (<3) | Broaden search terms |
+| W003 | warning | All hypotheses inconclusive | Marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Question parsed and investigation directory created
+- [ ] Evidence collected and logged to evidence.ndjson
+- [ ] At least 1 hypothesis formed and tested
+- [ ] understanding.md tracks evolving understanding
+- [ ] report.md written with answer and evidence trail
+- [ ] Findings appended to lessons.jsonl with stable INS-ids
+- [ ] 3-strike escalation triggered if all hypotheses fail
+</success_criteria>

package/codex/maestro-flow/commands/learn/retro.md

@@ -0,0 +1,83 @@
+---
+name: learn-retro
+description: Unified retrospective via CSV wave pipeline. Git lens (commit metrics, session detection, hotspots) and decision lens (multi-perspective evaluation via 3 parallel agents) with lens-based selection. Persists insights to lessons.jsonl.
+argument-hint: "[-y|--yes] [-c|--concurrency N] [--continue] \"[--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--compare]\""
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation.
+Two lenses, usable independently or together:
+- **git**: Commit metrics, session detection, per-author breakdown, file hotspots, trends
+- **decision**: Decision tracing across wiki/specs/git, multi-perspective evaluation via 3 parallel agents
+
+Works on raw git history and wiki/spec data — does not require completed phase artifacts.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens:** `--lens git` | `--lens decision` | `--lens all` (default)
+
+**Git flags:** `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare`
+**Decision flags:** `--phase N`, `--tag <tag>`, `--id <id>`
+
+**Output**: `.workflow/learning/retro-{date}.md` + `retro-{date}.json`
+</context>
+
+<execution>
+
+### Phase 1: Parse + Select Lenses
+
+### Phase 2: Git Lens (skip if --lens decision)
+**Sequential data gathering** (parallel git commands):
+- Commit stats with shortstat
+- Per-commit numstat for test/production LOC split
+- Timestamps for session detection (>2hr gap clustering)
+- File hotspots (most frequently changed)
+- Per-author commit counts
+
+**Compute**: commits, LOC, test ratio, churn rate, active days, sessions, per-author breakdown.
+**Trend comparison** if prior `retro-*.json` exists.
+
+### Phase 3: Decision Lens (skip if --lens git)
+**3a: Collect decisions** from wiki, specs, git log, phase context, lessons.jsonl.
+**3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
+
+**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
+
+| id | perspective | focus |
+|----|------------|-------|
+| 1 | technical | Implementation vs intent, context drift. Grade: sound/degraded/violated |
+| 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
+| 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
+
+**3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
+
+### Phase 4: Unified Report
+Write `retro-{date}.md` + `retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
+
+### Phase 5: Persist
+Append insights to `lessons.jsonl` (source: "retro-git" or "retro-decision"). Display summary.
+
+**Next steps:** `/learn-follow <path>`, `/quality-auto-test <area>`, `/learn-investigate <question>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Not inside git repo (git lens) | Navigate to git repo |
+| E002 | error | No commits in time window | Increase --days |
+| E003 | error | No decisions found (decision lens) | Check wiki/specs content |
+| W001 | warning | .workflow/learning/ not found | Auto-bootstrap |
+| W002 | warning | No prior retro for comparison | First retro establishes baseline |
+| W003 | warning | Decision perspective agent failed | Proceed with partial evaluation |
+</error_codes>
+
+<success_criteria>
+- [ ] Lens selection parsed correctly
+- [ ] Git lens: metrics computed, sessions detected, hotspots identified
+- [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
+- [ ] Unified report written to retro-{date}.md + retro-{date}.json
+- [ ] lessons.jsonl appended with insights (stable INS-ids)
+</success_criteria>