maestro-flow 0.4.8 → 0.4.10

package/.agy/skills/codify-to-knowhow/phases/04-index-verify.md

@@ -0,0 +1,119 @@
+# Phase 4: Index and Verify
+
+刷新 wiki 索引，验证所有创建的资产已正确索引和链接。
+
+## Objective
+
+- 刷新 wiki-index.json 以包含新创建的资产
+- 验证 knowhow 文件存在并已索引
+- 验证 spec 条目已写入
+- 验证 ref 链接从 spec 指向 knowhow
+- 输出完成报告
+
+## Execution
+
+### Step 4.1: Refresh Wiki Index
+
+触发 wiki 索引刷新以识别新增的 knowhow 文件：
+
+```bash
+# 刷新 wiki 索引
+maestro wiki health 2>/dev/null || echo "Wiki index refresh skipped (command not available)"
+```
+
+索引刷新确保 `wiki-index.json` 包含新创建的 AST-/DCS- 文件的 WikiEntry。
+
+### Step 4.2: Verify Knowhow Files
+
+检查所有预期的 knowhow 文件是否存在：
+
+```bash
+echo "=== Knowhow 资产验证 ==="
+
+# 必需文件
+for file in ${knowhowPaths}; do
+  if test -f "$file"; then
+    echo "  OK: $file"
+  else
+    echo "  MISSING: $file"
+  fi
+done
+```
+
+### Step 4.3: Verify Spec Entries
+
+检查 spec 文件中是否包含新增的条目：
+
+```bash
+echo "=== Spec 条目验证 ==="
+
+# 检查 coding-conventions.md 中是否含 slug 相关条目
+grep -c "${slug}" .workflow/specs/coding-conventions.md 2>/dev/null && \
+  echo "  OK: coding-conventions.md (${slug} entries found)" || \
+  echo "  MISSING: No ${slug} entries in coding-conventions.md"
+
+# 检查 architecture-constraints.md 中是否含 slug 相关条目
+grep -c "${slug}" .workflow/specs/architecture-constraints.md 2>/dev/null && \
+  echo "  OK: architecture-constraints.md (${slug} entries found)" || \
+  echo "  MISSING: No ${slug} entries in architecture-constraints.md"
+```
+
+### Step 4.4: Verify Ref Links
+
+检查 spec 条目中的 ref 属性指向的 knowhow 文件是否存在：
+
+```bash
+echo "=== Ref 链接验证 ==="
+
+# 从 spec 文件中提取 ref 属性值
+refs=$(grep -oP 'ref="knowhow/[^"]*"' .workflow/specs/coding-conventions.md .workflow/specs/architecture-constraints.md 2>/dev/null | grep "${slug}" || true)
+
+if [ -n "$refs" ]; then
+  echo "$refs" | while IFS= read -r ref; do
+    # 提取文件路径
+    filepath=$(echo "$ref" | grep -oP 'knowhow/[^"]*')
+    if test -f ".workflow/$filepath"; then
+      echo "  OK: $filepath"
+    else
+      echo "  BROKEN: $filepath (file not found)"
+    fi
+  done
+else
+  echo "  WARNING: No ref links found for ${slug}"
+fi
+```
+
+### Step 4.5: Generate Completion Report
+
+```
+=== Codify to Knowhow 完成 ===
+
+包: {slug}
+来源: {packagePath}
+
+Knowhow 资产:
+  AST-{slug}-tokens.md       — 设计 token 资产
+  AST-{slug}-components.md   — 组件模式资产
+  DCS-{slug}-decisions.md    — 设计决策 {仅当有冲突}
+
+Spec 条目 ({specEntryCount} 条):
+  coding: 颜色约定, 排版约定, 间距约定
+  arch: 组件分类约束{, 设计决策约束 — 仅当有冲突}
+
+Ref 链接: spec → knowhow 桥梁已建立
+Wiki 索引: 已刷新
+
+后续操作:
+  maestro wiki list --category coding    # 按角色浏览
+  maestro spec load --keyword {slug}    # 加载相关 spec
+  maestro wiki load <id>                # 加载详文
+```
+
+## Output
+
+- **Report**: 验证结果（所有资产/条目/链接状态）
+- **TodoWrite**: Mark Phase 4 completed (all tasks done)
+
+## Completion
+
+Codify to Knowhow 已完成。设计包已固化为知识资产。

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

@@ -0,0 +1,118 @@
+---
+name: learn-decompose
+description: Extract design patterns from code into specs and wiki
+argument-hint: <path|module> [--patterns <list>] [--save-spec] [--save-wiki]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Systematic pattern extraction: analyze module across 4 dimensions using parallel agents, catalog findings with code anchors, persist to specs/wiki. Produces reusable pattern catalog.
+</purpose>
+
+<context>
+$ARGUMENTS — target path/module and optional flags.
+
+**Target resolution**: file path → that file; directory → all source files; module name → Glob `src/**/{module}*`.
+
+**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
+
+**Storage read**: target files + `coding-conventions.md` + `specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-decompose-{slug}-{date}.md` + append `specs/learnings.md`
+</context>
+
+<state_machine>
+
+<states>
+S_RESOLVE    — 解析 target 为具体文件列表                PERSIST: —
+S_DEDUP      — 加载已有 patterns 用于去重                PERSIST: —
+S_ANALYZE    — 4 维度并行 Agent 分析                     PERSIST: —
+S_CROSSREF   — 交叉引用、去重、标记状态                   PERSIST: —
+S_CATALOG    — 生成 pattern catalog 报告                  PERSIST: outputs
+S_PERSIST    — 写文件 + 可选 spec-add/wiki create         PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_DEDUP       WHEN: file list resolved
+  → S_RESOLVE     WHEN: unresolvable                     DO: ask_question
+
+S_DEDUP:
+  → S_ANALYZE     DO: read coding-conventions.md + specs/learnings.md → build known pattern set
+
+S_ANALYZE:
+  → S_CROSSREF    DO: A_PARALLEL_DIMENSION_ANALYSIS
+
+S_CROSSREF:
+  → S_CATALOG     DO: A_CROSSREF_DEDUP
+
+S_CATALOG:
+  → S_PERSIST     DO: write KNW-decompose report (grouped by dimension: pattern table + details)
+
+S_PERSIST:
+  → END           DO: append specs/learnings.md [+ spec-add if --save-spec] [+ wiki note if --save-wiki]
+
+</transitions>
+
+<actions>
+
+### A_PARALLEL_DIMENSION_ANALYSIS
+
+Spawn 4 Agents in single message:
+
+| Agent | Dimension | Looks for |
+|-------|-----------|-----------|
+| 1 | Structural | Class hierarchy, composition, DI/IoC, Factory/Builder/Singleton, barrel exports |
+| 2 | Behavioral | Event flow, middleware chains, observer/pub-sub, command/strategy, state machines |
+| 3 | Data | Repository/DAO, DTO pipelines, caching (memo/LRU/TTL), serialization, schema validation |
+| 4 | Error | Error boundaries, retry/backoff/circuit-breaker, fallback chains, guard clauses, logging |
+
+If `--patterns` specified: agents focus only on named patterns.
+
+Each agent returns: `[{ name, dimension, confidence (high/medium/low), anchors [file:line], description, rationale, tradeoffs }]`
+
+### A_CROSSREF_DEDUP
+
+For each finding, match against known pattern set:
+| Status | Condition |
+|--------|-----------|
+| documented | Already in coding-conventions.md |
+| known | In specs/learnings.md |
+| new | Not seen before |
+
+Flag contradictions (finding conflicts with documented convention). Merge duplicates across agents (same pattern found by multiple dimensions).
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | No source files in target | Check target has .ts/.js files |
+| W001 | One+ dimension agent failed | Proceed with available dimensions |
+| W003 | Large target (>50 files) | Consider --patterns filter |
+</error_codes>
+
+<success_criteria>
+- [ ] 4 dimension agents spawned in parallel, findings with anchors
+- [ ] Cross-reference: documented/known/new status assigned
+- [ ] Pattern catalog written + specs/learnings.md appended
+</success_criteria>
+
+<next_step_routing>
+- Follow-along → `/learn-follow <anchor-file>`
+- Second opinion → `/learn-second-opinion <target>`
+- Add to specs → `/spec-add coding ...`
+</next_step_routing>

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

@@ -0,0 +1,129 @@
+---
+name: learn-follow
+description: Guided reading of code or wiki to extract patterns
+argument-hint: <path|wiki-id|topic> [--depth shallow|deep] [--save-wiki]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Guided reading: walk through content section-by-section using forcing questions to extract patterns, identify assumptions, and build an understanding map. Findings persist to `specs/learnings.md` as `<spec-entry>` blocks.
+</purpose>
+
+<context>
+$ARGUMENTS — target and optional flags.
+
+**Target resolution** (auto-detected):
+| Input | Resolution |
+|-------|-----------|
+| File path (contains `/` or `\`) | Read source file |
+| Wiki ID (`<type>-<slug>`) | `maestro wiki get <id>` |
+| Topic string | `maestro wiki search "<topic>"` → top result; fallback: Grep src/ |
+
+**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
+
+**Storage read**: target file + wiki forward/backlinks + `coding-conventions.md` + `specs/learnings.md` (dedup)
+**Storage write**: `.workflow/knowhow/KNW-follow-{slug}-{date}.md` + append `specs/learnings.md`
+</context>
+
+<state_machine>
+
+<states>
+S_RESOLVE      — 解析 target (file/wiki/topic)              PERSIST: —
+S_CONTEXT      — 构建 1-hop 上下文邻域                       PERSIST: —
+S_ORDER        — 确定阅读顺序                                PERSIST: —
+S_READ         — 逐节应用 forcing questions                   PERSIST: —
+S_EXTRACT      — 提取 patterns、cross-ref conventions         PERSIST: —
+S_PERSIST      — 写 understanding map + spec-entry 块         PERSIST: knowhow files
+</states>
+
+<transitions>
+
+S_RESOLVE:
+  → S_CONTEXT     WHEN: target resolved
+  → S_RESOLVE     WHEN: unresolvable                       DO: ask_question with suggestions
+
+S_CONTEXT:
+  → S_ORDER       DO: A_BUILD_CONTEXT_WEB
+
+S_ORDER:
+  → S_READ        DO: A_BUILD_READING_ORDER
+
+S_READ:
+  → S_EXTRACT     DO: A_GUIDED_READ (apply 4 forcing questions per section)
+
+S_EXTRACT:
+  → S_PERSIST     DO: A_EXTRACT_PATTERNS
+
+S_PERSIST:
+  → END           DO: write KNW-follow + append specs/learnings.md [+ wiki note if --save-wiki]
+
+</transitions>
+
+<actions>
+
+### A_BUILD_CONTEXT_WEB
+
+| Target type | Context |
+|-------------|---------|
+| Wiki entry | `maestro wiki forward <id>` + `maestro wiki backlinks <id>` → read top 3 related |
+| Code file | Parse imports → dependency files; grep exports → reverse deps; read top 3 dependents (50 lines) |
+| Directory | List files, identify entry points → build reading order: entry → core → utils → tests |
+
+### A_BUILD_READING_ORDER
+
+- Single file: split by function/class/export boundaries
+- Wiki entry: split by markdown headings
+- Directory: order by dependency (entry points first, leaf last)
+- `--depth shallow`: top-level structure only; `--depth deep`: every body and branch
+
+### A_GUIDED_READ
+
+For each section, apply 4 forcing questions:
+
+| # | Question | Extracts |
+|---|----------|----------|
+| 1 | "What pattern is being used here?" | Design patterns, idioms, conventions |
+| 2 | "Why this approach instead of alternatives?" | Trade-offs, rejected options |
+| 3 | "What assumption does this depend on?" | Implicit contracts, input shape, ordering |
+| 4 | "What would break if this changed?" | Fragility, downstream effects |
+
+### A_EXTRACT_PATTERNS
+
+Extract: design patterns (with file:line anchors), naming conventions, error handling approach, data flow, assumptions.
+Cross-ref against `coding-conventions.md`: documented → "confirmed convention", undocumented → "candidate for spec-add".
+
+Write understanding map: Key Concepts, Patterns (table: name/location/convention status), Assumptions, Open Questions, Connections.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| W002 | coding-conventions.md not found | All patterns marked "unknown status" |
+| W003 | Target > 1000 lines | Auto-switch to shallow; use --depth deep to override |
+</error_codes>
+
+<success_criteria>
+- [ ] 4 forcing questions applied per section
+- [ ] Patterns extracted with file:line anchors and convention cross-ref
+- [ ] Understanding map + spec-entry blocks written
+</success_criteria>
+
+<next_step_routing>
+- Deep pattern dive → `/learn-decompose <path>`
+- Add to specs → `/spec-add coding <description>`
+- Second opinion → `/learn-second-opinion <file>`
+</next_step_routing>

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

@@ -0,0 +1,154 @@
+---
+name: learn-investigate
+description: Investigate questions with hypothesis testing and evidence logging
+argument-hint: <question> [--scope <path>] [--max-hypotheses N]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Systematic investigation for understanding questions (not bug-fixing). 4-phase scientific method with scope lock and 3-strike escalation. Produces evidence trails and understanding docs that persist to the learning system.
+
+Unlike `quality-debug` (fix bugs during execution), this answers "how does X work?", "why does Y happen?", "what if Z?".
+</purpose>
+
+<context>
+$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)
+
+**Storage write**:
+- `.workflow/knowhow/KNW-investigate-{slug}/evidence.ndjson` — structured evidence (one JSON line per item)
+- `.workflow/knowhow/KNW-investigate-{slug}/understanding.md` — evolving understanding
+- `.workflow/knowhow/KNW-investigate-{slug}/report.md` — final report
+- `specs/learnings.md` — appended `<spec-entry>` blocks
+
+**Storage read**: source files in scope + `maestro wiki search` + `specs/learnings.md` + `debug-notes.md` + `codebase/architecture.md`
+</context>
+
+<state_machine>
+
+<states>
+S_FRAME          — 解析问题、确定 scope、搜索先验知识          PERSIST: understanding.md (initial)
+S_EVIDENCE       — 系统收集证据                                PERSIST: evidence.ndjson
+S_PATTERN        — 比对已知模式                                PERSIST: understanding.md (patterns)
+S_HYPOTHESIZE    — 生成假设列表                                PERSIST: understanding.md (hypotheses)
+S_CLI_EXPLORE    — CLI 辅助探索（可选）                         PERSIST: evidence.ndjson (append)
+S_TEST           — 逐假设测试                                  PERSIST: evidence.ndjson + understanding.md
+S_ESCALATE       — 3-strike 升级                               PERSIST: —
+S_REPORT         — 综合报告 + persist                          PERSIST: report.md + specs/learnings.md
+</states>
+
+<transitions>
+
+S_FRAME:
+  → S_EVIDENCE    DO: A_FRAME_QUESTION
+
+S_EVIDENCE:
+  → S_PATTERN     DO: A_COLLECT_EVIDENCE
+
+S_PATTERN:
+  → S_HYPOTHESIZE DO: match evidence against debug-notes.md + 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:
+  → S_TEST        DO: A_CLI_SUPPLEMENT (maestro delegate --role explore --mode analysis, run_in_background, STOP)
+
+S_TEST:
+  → S_REPORT      WHEN: hypothesis confirmed                  DO: A_TEST_HYPOTHESIS
+  → S_REPORT      WHEN: all hypotheses tested (some confirmed) DO: A_TEST_HYPOTHESIS
+  → S_ESCALATE    WHEN: max_hypotheses all failed              DO: A_TEST_HYPOTHESIS
+
+S_ESCALATE:
+  → S_HYPOTHESIZE WHEN: user broadens scope or provides new hypothesis   DO: ask_question
+  → S_REPORT      WHEN: user selects "Escalate" or still stuck          DO: mark INCONCLUSIVE
+
+S_REPORT:
+  → END           DO: A_SYNTHESIZE_REPORT
+
+</transitions>
+
+<actions>
+
+### A_FRAME_QUESTION
+
+1. Parse question, generate slug, create KNW-investigate-{slug}/
+2. Search prior knowledge: `maestro wiki search "<question>"` + search specs/learnings.md + read debug-notes.md
+3. Write initial understanding.md (question, prior knowledge summary, scope, timestamp)
+
+### A_COLLECT_EVIDENCE
+
+Parallel evidence gathering:
+1. Code search: Grep keywords from question
+2. File inspection: Read most relevant files
+3. Import tracing: follow dependency chain
+4. Git history: `git log --oneline -10 -- <relevant-files>`
+
+Each item → append evidence.ndjson: `{ts, type (code|git|search|doc), source (file:line), relevance (high|medium|low), content, note}`
+
+### A_FORM_HYPOTHESES
+
+Generate ranked hypotheses: each is specific, testable claim about "how/why".
+Rank by plausibility (evidence strength). Write to understanding.md:
+- `[HIGH]` hypothesis — Evidence: {refs}
+- `[MEDIUM]` hypothesis — Evidence: {refs}
+
+### A_CLI_SUPPLEMENT
+
+```
+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
+```
+Run_in_background, STOP, wait. On callback: append to evidence.ndjson.
+
+### A_TEST_HYPOTHESIS
+
+For each hypothesis (rank order):
+1. Design test: what evidence would confirm/disprove?
+2. Execute: code trace, targeted search, data inspection
+3. Record: append evidence.ndjson with type: "test"
+4. Update: mark hypothesis confirmed / disproved / inconclusive
+
+### A_SYNTHESIZE_REPORT
+
+Write report.md: Answer (or INCONCLUSIVE), Evidence Trail table, Hypotheses Tested table, Key Learnings, Open Questions.
+Append to specs/learnings.md: confirmed → roles="implement", disproved → roles="analyze" (gotcha).
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | --scope path not found | Check path |
+| W002 | Very few evidence matches (<3) | Broaden search terms or expand scope |
+| W003 | All hypotheses inconclusive | Investigation marked INCONCLUSIVE |
+</error_codes>
+
+<success_criteria>
+- [ ] Evidence collected and logged to evidence.ndjson (structured NDJSON)
+- [ ] At least 1 hypothesis formed and tested
+- [ ] 3-strike escalation triggered if all fail
+- [ ] Report + spec-entry blocks written
+</success_criteria>
+
+<next_step_routing>
+- Save to specs → `/spec-add debug <finding>`
+- Follow code → `/learn-follow <path>`
+- Decompose patterns → `/learn-decompose <module>`
+</next_step_routing>

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

@@ -0,0 +1,159 @@
+---
+name: learn-retro
+description: Retrospective of git activity and decision quality
+argument-hint: [--lens git|decision|all] [--days N] [--author <name>] [--area <path>] [--phase N] [--tag <tag>] [--id <id>] [--compare]
+allowed-tools:
+  - ask_question
+  - define_subagent
+  - grep_search
+  - invoke_subagent
+  - manage_subagents
+  - run_command
+  - send_message
+  - view_file
+  - write_to_file
+---
+<purpose>
+Unified retrospective combining git activity analysis and decision quality evaluation. Works on raw git history and wiki/spec data. Two lenses (git, decision), usable independently or together.
+
+All insights persist to `specs/learnings.md` as `<spec-entry>` blocks.
+</purpose>
+
+<context>
+$ARGUMENTS — lens selection and scope flags.
+
+**Lens**: `--lens git` | `--lens decision` | `--lens all` (default: all)
+
+**Git lens flags**: `--days N` (default: 7), `--author <name>`, `--area <path>`, `--compare` (vs prior retro)
+**Decision lens flags**: `--phase N`, `--tag <tag>`, `--id <id>` (single decision by wiki/INS id)
+
+**Storage write**:
+- `.workflow/knowhow/KNW-retro-{date}.md` — unified report
+- `.workflow/knowhow/KNW-retro-{date}.json` — structured metrics
+- `specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
+
+**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `specs/learnings.md`, wiki specs, `architecture-constraints.md`, phase context files
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE       — 解析 lens + flags                           PERSIST: —
+S_GIT         — git 活动分析（lens=git/all 时）              PERSIST: metrics
+S_DECISION    — 决策质量评估（lens=decision/all 时）         PERSIST: evaluations
+S_REPORT      — 生成统一报告                                 PERSIST: .md + .json
+S_PERSIST     — 写 spec-entry 块                             PERSIST: specs/learnings.md
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_GIT         WHEN: lens == git OR all               DO: ensure .workflow/knowhow/ exists (mkdir -p)
+  → S_DECISION    WHEN: lens == decision                  DO: ensure .workflow/knowhow/ exists (mkdir -p)
+
+S_GIT:
+  → S_DECISION    WHEN: lens == all                          DO: A_GIT_ANALYSIS
+  → S_REPORT      WHEN: lens == git                          DO: A_GIT_ANALYSIS
+
+S_DECISION:
+  → S_REPORT      DO: A_DECISION_ANALYSIS
+
+S_REPORT:
+  → S_PERSIST     DO: write KNW-retro-{date}.md + .json
+
+S_PERSIST:
+  → END           DO: append insights to specs/learnings.md via `maestro spec add learning`
+  RULE: INS-id = hash(lens + metric_or_decision_id + date) for cross-session stability
+
+</transitions>
+
+<actions>
+
+### A_GIT_ANALYSIS
+
+**Parallel git commands**:
+```bash
+git log --since="{start}" --format="%H|%aN|%ae|%ai|%s" --shortstat
+git log --since="{start}" --format="COMMIT:%H|%aN" --numstat
+git log --since="{start}" --format="%at|%aN|%ai|%s" | sort -n
+git log --since="{start}" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20
+git shortlog --since="{start}" -sn --no-merges
+```
+Apply --author and --area filters.
+
+**Compute metrics**:
+
+| Metric | Formula |
+|--------|---------|
+| Test ratio | test_insertions / total_insertions * 100% |
+| Churn rate | files changed >2x / total unique files |
+| Sessions | Cluster commits by >2hr gaps in timestamps |
+| LOC/session-hour | net_loc / total_session_hours |
+
+**Per-author breakdown**: commits, LOC, top 3 areas, test ratio, session count.
+
+**Trend** (if --compare or prior KNW-retro-*.json exists): compute deltas, flag >20% changes.
+
+**Distill insights**: high churn files (instability), low test ratio areas (<20%), session patterns, area drift vs roadmap.
+
+### A_DECISION_ANALYSIS
+
+**Collect** (parallel):
+```bash
+maestro wiki search "decision" --json
+maestro wiki list --type spec --json
+git log --oneline --all --grep="decision\|chose\|decided" -20
+```
+Plus: architecture-constraints.md, phase context Locked/Deferred sections, specs/learnings.md.
+Apply --phase/--tag/--id filters.
+
+**Build registry** per decision: id, title, source, date, rationale, alternatives, phase, implementation_evidence [file paths].
+
+**Evaluate** — spawn 3 Agents in single message:
+
+| Agent | Dimension | Grades |
+|-------|-----------|--------|
+| Technical Soundness | Implementation matches intent? Context changed? | sound / degraded / violated |
+| Cost Assessment | Complexity added? Coupling/debt? | low-cost / acceptable / expensive / debt-creating |
+| Alternative Hindsight | Right call with current knowledge? Reversible? | confirmed / questionable / should-revisit |
+
+**Classify lifecycle**:
+
+| Status | Criteria |
+|--------|---------|
+| Validated | sound + low/acceptable + confirmed |
+| Aging | sound + expensive + confirmed |
+| Questionable | degraded/violated + questionable |
+| Stale | any + should-revisit |
+| Reversed | code contradicts decision |
+
+**Recommend**: Aging → tech debt review, Questionable → create issue, Stale → refresh, Reversed → document reversal.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E001 | Not in git repo (git lens) | Navigate to git repo |
+| E002 | No commits in window (git lens) | Increase --days |
+| E003 | No decisions found (decision lens) | Check wiki/specs or provide --id |
+| E004 | --id not found in wiki or knowhow | Verify the decision ID exists |
+| W002 | No prior retro for comparison | Skip trend; first retro = baseline |
+| W003 | One perspective agent failed | Proceed with available perspectives |
+</error_codes>
+
+<success_criteria>
+- [ ] Git lens: metrics computed (commits, LOC, test ratio, churn, sessions), insights distilled
+- [ ] Decision lens: decisions collected, 3 agents evaluated in parallel, lifecycle classified
+- [ ] Unified report + structured JSON written
+- [ ] specs/learnings.md appended with stable INS-ids
+</success_criteria>
+
+<next_step_routing>
+- Browse insights → `/manage-learn list --tag retro`
+- Deep dive churn → `/learn-follow <path>`
+- Fix test gaps → `/quality-auto-test <area>`
+- Investigate stale decision → `/learn-investigate <question>`
+</next_step_routing>