maestro-flow 0.1.4 → 0.2.1

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

@@ -1,125 +1,125 @@
----
-name: quality-review
-description: Tiered code review (quick/standard/deep) with parallel agents, severity classification, and auto-issue creation
-argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" — complementing maestro-verify ("is the goal met?") and quality-test ("does it work for users?").
-
-Supports three review levels that scale with task depth:
-
-**Quick** — Single-pass inline scan, no agents. For small changes (≤3 files) or scratch tasks.
-  - Dimensions: correctness + security only
-  - No deep-dive, issues created for critical only
-
-**Standard** — Parallel agent review across all dimensions. Default for most phases.
-  - Dimensions: all 6 (correctness, security, performance, architecture, maintainability, best-practices)
-  - Auto deep-dive if critical findings > 0
-  - Issues created for critical + high
-
-**Deep** — Full agent review with forced multi-iteration deep-dive and cross-file impact analysis. For complex/critical phases.
-  - Dimensions: all 6
-  - Forced deep-dive (max 3 iterations) with impact radius analysis
-  - Issues created for critical + high + medium
-
-Level auto-detection when not specified:
-  - ≤3 changed files → quick
-  - 4-19 changed files → standard
-  - ≥20 changed files OR phase marked critical in index.json → deep
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/review.md
-</required_reading>
-
-<deferred_reading>
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required — phase number or slug)
-
-**Flags:**
-- `--level quick|standard|deep` — Explicit review level (default: auto-detect from file count)
-- `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
-- `--skip-specs` — Skip loading project specs as review context
-
-Context files resolved from `.workflow/phases/{NN}-{slug}/`:
-- index.json (phase metadata, execution results)
-- plan.json (task overview)
-- .task/TASK-{NNN}.json (task definitions with file lists)
-- .summaries/TASK-{NNN}-summary.md (execution results)
-- verification.json (if exists — incorporate verification gaps as review context)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/review.md' completely.
-
-**Report format on completion:**
-
-```
-=== CODE REVIEW RESULTS ===
-Phase:     {phase_name}
-Level:     {quick | standard | deep}
-Files:     {files_reviewed} files across {dimensions_count} dimensions
-Duration:  {duration}
-
-Severity Distribution:
-  Critical: {critical_count}
-  High:     {high_count}
-  Medium:   {medium_count}
-  Low:      {low_count}
-
-Top Issues:
-  1. [{severity}] {finding_id}: {title} ({file}:{line})
-  2. ...
-
-Verdict: {PASS | WARN | BLOCK}
-Issues Created: {issue_count}
-
-Files:
-  {phase_dir}/review.json
-
-Next steps:
-  {verdict_based_routing}
-```
-
-**Next-step routing by verdict:**
-- PASS → Skill({ skill: "quality-test", args: "{phase}" })
-- PASS + low test coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
-- WARN → Skill({ skill: "quality-test", args: "{phase}" }) (proceed with caveats)
-- BLOCK → Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) (fix critical findings first)
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
-| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
-| E003 | error | No execution results found (no task summaries) | Verify execution completed with task summaries |
-| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
-| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
-| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
-</error_codes>
-
-<success_criteria>
-- [ ] Phase resolved and changed files collected from task summaries
-- [ ] Review level determined (explicit flag or auto-detected)
-- [ ] Project specs loaded as review context (unless --skip-specs)
-- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
-- [ ] All dimension results aggregated with severity classification
-- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
-- [ ] review.json written with complete findings, severity distribution, verdict
-- [ ] Issues auto-created based on level thresholds
-- [ ] index.json updated with review status
-- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
-</success_criteria>
+---
+name: quality-review
+description: Tiered code review (quick/standard/deep) with parallel agents, severity classification, and auto-issue creation
+argument-hint: "<phase> [--level quick|standard|deep] [--dimensions security,architecture,...] [--skip-specs]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Run multi-dimensional code review on a completed phase's changed files. Answers the question "is this code good?" — complementing maestro-verify ("is the goal met?") and quality-test ("does it work for users?").
+
+Supports three review levels that scale with task depth:
+
+**Quick** — Single-pass inline scan, no agents. For small changes (≤3 files) or scratch tasks.
+  - Dimensions: correctness + security only
+  - No deep-dive, issues created for critical only
+
+**Standard** — Parallel agent review across all dimensions. Default for most phases.
+  - Dimensions: all 6 (correctness, security, performance, architecture, maintainability, best-practices)
+  - Auto deep-dive if critical findings > 0
+  - Issues created for critical + high
+
+**Deep** — Full agent review with forced multi-iteration deep-dive and cross-file impact analysis. For complex/critical phases.
+  - Dimensions: all 6
+  - Forced deep-dive (max 3 iterations) with impact radius analysis
+  - Issues created for critical + high + medium
+
+Level auto-detection when not specified:
+  - ≤3 changed files → quick
+  - 4-19 changed files → standard
+  - ≥20 changed files OR phase marked critical in index.json → deep
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
+<deferred_reading>
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index after review
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required — phase number or slug)
+
+**Flags:**
+- `--level quick|standard|deep` — Explicit review level (default: auto-detect from file count)
+- `--dimensions <list>` — Comma-separated subset of dimensions to review (overrides level defaults)
+- `--skip-specs` — Skip loading project specs as review context
+
+Context files resolved from `.workflow/phases/{NN}-{slug}/`:
+- index.json (phase metadata, execution results)
+- plan.json (task overview)
+- .task/TASK-{NNN}.json (task definitions with file lists)
+- .summaries/TASK-{NNN}-summary.md (execution results)
+- verification.json (if exists — incorporate verification gaps as review context)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/review.md' completely.
+
+**Report format on completion:**
+
+```
+=== CODE REVIEW RESULTS ===
+Phase:     {phase_name}
+Level:     {quick | standard | deep}
+Files:     {files_reviewed} files across {dimensions_count} dimensions
+Duration:  {duration}
+
+Severity Distribution:
+  Critical: {critical_count}
+  High:     {high_count}
+  Medium:   {medium_count}
+  Low:      {low_count}
+
+Top Issues:
+  1. [{severity}] {finding_id}: {title} ({file}:{line})
+  2. ...
+
+Verdict: {PASS | WARN | BLOCK}
+Issues Created: {issue_count}
+
+Files:
+  {phase_dir}/review.json
+
+Next steps:
+  {verdict_based_routing}
+```
+
+**Next-step routing by verdict:**
+- PASS → Skill({ skill: "quality-test", args: "{phase}" })
+- PASS + low test coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
+- WARN → Skill({ skill: "quality-test", args: "{phase}" }) (proceed with caveats)
+- BLOCK → Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) (fix critical findings first)
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | No execution results found (no task summaries) | Verify execution completed with task summaries |
+| E004 | error | No changed files detected in phase | Verify execution completed with task summaries |
+| W001 | warning | Some dimension agents failed, partial results | Retry failed dimensions or accept partial results |
+| W002 | warning | Deep-dive iteration limit reached with unresolved criticals | Accept current findings or escalate manually |
+</error_codes>
+
+<success_criteria>
+- [ ] Phase resolved and changed files collected from task summaries
+- [ ] Review level determined (explicit flag or auto-detected)
+- [ ] Project specs loaded as review context (unless --skip-specs)
+- [ ] Dimension reviews executed (inline for quick, parallel agents for standard/deep)
+- [ ] All dimension results aggregated with severity classification
+- [ ] Deep-dive completed if triggered (standard: auto, deep: forced)
+- [ ] review.json written with complete findings, severity distribution, verdict
+- [ ] Issues auto-created based on level thresholds
+- [ ] index.json updated with review status
+- [ ] Next step routed by verdict (PASS→test, WARN→test with caveats, BLOCK→plan --gaps)
+</success_criteria>

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

@@ -39,6 +39,7 @@ Phase or task: $ARGUMENTS (optional)
 Context files resolved from target directory:
 - verification.json (must_haves, gaps from maestro-verify)
 - validation.json (coverage, requirement mapping)
+- review.json (findings from quality-review, if exists)
 - index.json (success_criteria, execution results)
 - plan.json (task overview)
 - .summaries/TASK-*.md (execution summaries)
@@ -48,6 +49,11 @@ Context files resolved from target directory:
 <execution>
 Follow '~/.maestro/workflows/test.md' completely.
 
+**Review findings integration (when review.json exists):**
+- Extract critical/high findings from review.json.findings_by_dimension as additional test scenarios
+- These review-derived scenarios are prioritized and marked `source: "review_finding"`
+- When review.json verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop without user confirmation (Step 12 auto-fix condition)
+
 **Next-step routing on completion:**
 - All tests pass → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
 - Issues found, --auto-fix ran and succeeded → Skill({ skill: "maestro-verify", args: "{phase}" })

package/.claude/commands/wiki-connect.md

@@ -0,0 +1,168 @@
+---
+name: wiki-connect
+description: Surface hidden connections in the wiki knowledge graph and suggest or apply new links
+argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
+
+Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, health scoring) — no equivalent in gstack. Directly improves the quality of all downstream wiki consumers (search, digest, follow-along).
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Flags:**
+- `--scope <type>` — Limit analysis to a wiki type (spec, phase, memory, note, lesson, issue). Default: all types.
+- `--min-similarity N` — Minimum similarity score threshold 0.0-1.0 (default: 0.3)
+- `--fix` — Auto-apply the top suggestions by updating wiki entries with new `related` links
+- `--max N` — Maximum number of suggestions to generate (default: 20)
+
+**Storage written:**
+- `.workflow/learning/wiki-connections-{YYYY-MM-DD}.md` — Connection analysis report
+- If `--fix`: wiki entries updated via `maestro wiki update` with new `related` links
+- `.workflow/learning/lessons.jsonl` — Graph structure insights (source: "wiki-connect")
+
+**Storage read (via maestro wiki CLI, offline mode):**
+- `maestro wiki list --json` — All wiki entries
+- `maestro wiki graph` — Full graph structure (forward + backlinks)
+- `maestro wiki health` — Current health score
+- `maestro wiki orphans` — Orphaned entries
+- `maestro wiki hubs` — Hub entries (most referenced)
+</context>
+
+<execution>
+
+### Stage 1: Load Wiki State
+Run these `maestro wiki` commands in parallel:
+
+```bash
+maestro wiki list --json
+maestro wiki health
+maestro wiki orphans
+maestro wiki hubs --top 10
+```
+
+Parse results:
+- Entry count, type distribution
+- Baseline health score (from `wiki health`)
+- Orphan list (entries with 0 in-degree and 0 out-degree)
+- Hub list (most-referenced entries)
+
+Apply `--scope` filter if provided.
+
+### Stage 2: Identify Connection Candidates
+For each entry, compute potential connections:
+
+**2a. Orphan Rescue:**
+For each orphan entry, search for related entries using:
+- `maestro wiki search "<orphan title>"` — BM25 match by title
+- Tag overlap: entries sharing 2+ tags with the orphan
+- Same phase: entries with matching `phaseRef`
+
+**2b. Missing Bidirectional Links:**
+For entries that have forward links but no corresponding backlink (A links to B, but B doesn't link to A), suggest adding the reverse link.
+
+**2c. Transitive Closure:**
+If A → B and B → C, but A has no link to C, and A and C share tags or are in the same phase, suggest A → C.
+
+**2d. Type Bridge:**
+Entries of different types that reference the same concept (e.g., a `spec-auth` and a `lesson-auth-gotcha`) but aren't linked.
+
+### Stage 3: Score Candidates
+For each candidate connection (source → target), compute similarity:
+
+```
+score = 0.4 × tag_overlap_ratio
+      + 0.3 × title_bm25_similarity
+      + 0.2 × same_phase_bonus
+      + 0.1 × type_bridge_bonus
+```
+
+- `tag_overlap_ratio`: shared_tags / max(source_tags, target_tags)
+- `title_bm25_similarity`: normalized BM25 score from wiki search
+- `same_phase_bonus`: 1.0 if same phaseRef, else 0.0
+- `type_bridge_bonus`: 1.0 if different types, else 0.0
+
+Filter by `--min-similarity`, rank descending, limit to `--max`.
+
+### Stage 4: Present Suggestions
+Display ranked connection suggestions:
+
+```
+== Wiki Connection Suggestions ==
+Baseline health: 72/100 | Orphans: 8 | Broken links: 3
+
+#  Score  Source              → Target              Reason
+1  0.85   memory-auth-flow    → spec-auth           tag overlap (auth, security) + same phase
+2  0.71   note-cache-pattern  → spec-performance    title BM25 match + type bridge
+3  0.65   lesson-retry-fix    → spec-error-handling  tag overlap (error, retry)
+...
+
+Projected health after fix: 81/100 (+9)
+```
+
+If NOT `--fix`: display and exit.
+If `--fix`: proceed to Stage 5.
+
+### Stage 5: Apply Connections (--fix only)
+For each accepted suggestion:
+1. Get current entry: `maestro wiki get <source-id> --json`
+2. Extract existing `related` list from frontmatter
+3. Append target-id to `related` if not already present
+4. Update: `maestro wiki update <source-id> --frontmatter "related: [existing..., new-target]"`
+5. Log success/failure
+
+After all updates:
+- Re-run `maestro wiki health` to get new health score
+- Report delta
+
+### Stage 6: Persist & Report
+1. Write `.workflow/learning/wiki-connections-{date}.md` with:
+   - Baseline and final health scores
+   - All suggestions (applied and unapplied)
+   - Orphan rescue results
+   - Graph structure observations (hub concentration, type distribution)
+2. Append graph insights to `lessons.jsonl`:
+   - `source: "wiki-connect"`, `category: "technique"`
+   - e.g., "Auth-related entries are poorly connected", "Phase 3 has 5 orphaned notes"
+3. Display summary
+
+**Next-step routing:**
+- Generate knowledge digest → `Skill({ skill: "wiki-digest", args: "<topic>" })`
+- Follow-along on orphan → `Skill({ skill: "learn-follow", args: "<wiki-id>" })`
+- View full graph → `maestro wiki graph`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `Skill({ skill: "maestro-init" })` |
+| E002 | error | `maestro wiki` CLI not available | Check maestro installation |
+| W001 | warning | No connection candidates found above threshold | Lower --min-similarity or check if graph is already well-connected |
+| W002 | warning | Some wiki update calls failed during --fix | Partial application; retry failed entries manually |
+| W003 | warning | Health score unchanged after fix | Connections may not have improved the specific health metrics |
+</error_codes>
+
+<success_criteria>
+- [ ] Wiki index loaded with entry count and type distribution
+- [ ] Baseline health score recorded
+- [ ] Orphans identified and rescue candidates generated
+- [ ] Connection candidates scored and ranked
+- [ ] Results filtered by --min-similarity and limited by --max
+- [ ] Suggestions displayed with scores and reasons
+- [ ] If --fix: entries updated with new `related` links
+- [ ] If --fix: new health score computed and delta reported
+- [ ] Report written to `wiki-connections-{date}.md`
+- [ ] Graph insights appended to `lessons.jsonl`
+- [ ] No unintended entry modifications (only `related` field changed)
+- [ ] Summary displayed with next-step routing
+</success_criteria>

package/.claude/commands/wiki-digest.md

@@ -0,0 +1,180 @@
+---
+name: wiki-digest
+description: Generate knowledge digest from wiki entries with theme clustering, gap analysis, and coverage heatmap
+argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Knowledge synthesis command that generates actionable digests from the wiki knowledge graph. Clusters entries by semantic theme, identifies knowledge gaps, and produces a coverage heatmap. Unique to maestro — leverages the wiki graph (BM25 search, backlinks, health) to surface trends and missing knowledge.
+
+Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
+</purpose>
+
+<context>
+Arguments: $ARGUMENTS
+
+**Scope resolution (auto-detected):**
+- `<topic>` — Search wiki for entries matching the topic via `maestro wiki search`
+- `--recent N` — Entries updated in the last N days
+- `--type <type>` — Filter by wiki type (spec, phase, memory, note, lesson, issue)
+- No arguments — digest of the entire wiki
+
+**Flags:**
+- `--format brief` — Compact summary, one paragraph per theme (default)
+- `--format full` — Detailed digest with per-entry summaries and full gap analysis
+
+**Storage written:**
+- `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.md` — Digest document
+- `.workflow/learning/lessons.jsonl` — Meta-insights about knowledge structure (source: "wiki-digest")
+
+**Storage read (via maestro wiki CLI, offline mode):**
+- `maestro wiki list --json` — All entries (or filtered)
+- `maestro wiki search <topic>` — Topic-scoped entries
+- `maestro wiki get <id>` — Entry bodies for summarization
+- `maestro wiki backlinks <id>` / `maestro wiki forward <id>` — Relationship context
+- `maestro wiki health` — Overall graph health
+- `.workflow/learning/lessons.jsonl` — Cross-reference for unlinked insights
+</context>
+
+<execution>
+
+### Stage 1: Scope & Load
+- Parse arguments to determine scope:
+  - Topic: `maestro wiki search "<topic>" --json` → matching entries
+  - Recent N: `maestro wiki list --json` → filter by `updated` within N days
+  - Type: `maestro wiki list --type <type> --json`
+  - All: `maestro wiki list --json`
+- Load entry metadata (id, title, tags, status, type, related, summary)
+- For `--format full`: also load entry bodies via `maestro wiki get <id>` for top entries
+- Run `maestro wiki health` for baseline metrics
+
+### Stage 2: Theme Clustering
+Group entries into 3-5 semantic themes using:
+
+1. **Tag co-occurrence**: entries sharing 2+ tags belong to the same theme
+2. **Title similarity**: BM25-based grouping (entries whose titles match each other's keywords)
+3. **Relationship proximity**: entries connected by `related` links cluster together
+4. **Type grouping**: if entries are all same type, sub-cluster by content
+
+For each theme:
+- Name: most common tag or dominant keyword
+- Entry count
+- Type distribution within theme
+- Status distribution (draft/active/completed/archived)
+
+### Stage 3: Per-Theme Analysis
+For each theme, produce:
+
+**Summary paragraph**: synthesize the key knowledge in this theme area (what do these entries collectively say?)
+
+**Key entries**: top 3-5 most important entries (by hub score / backlink count)
+
+**Gap detection**:
+- Broken links: `[[references]]` that don't resolve within the theme
+- Orphans: entries in this theme with no connections
+- Questions: entries with `?` in title or "TODO" / "TBD" markers in body
+- Missing perspectives: if theme has specs but no lessons, or issues but no decisions
+
+**Health**: per-theme health score (adapted from wiki health formula)
+
+### Stage 4: Cross-Reference with Lessons
+- Search `lessons.jsonl` for insights related to each theme
+- Identify unlinked insights: lessons that match a theme but are not referenced by any wiki entry in that theme
+- Flag these as "knowledge not yet connected to the graph"
+
+### Stage 5: Coverage Heatmap
+Build a matrix showing knowledge density by type × theme:
+
+```
+              Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
+spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
+phase         ████░      ███░░      ░░░░░      █████      ██░░░
+memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
+lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
+issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
+
+Legend: █ = entries exist, ░ = sparse/missing
+```
+
+Identify: which theme × type cells are empty? These are knowledge gaps.
+
+### Stage 6: Write Digest
+Produce `.workflow/learning/digest-{slug}-{date}.md`:
+
+```markdown
+# Knowledge Digest: {scope description}
+**Generated:** {date} | **Entries:** {count} | **Health:** {score}/100
+
+## Themes
+
+### 1. {Theme Name} ({N} entries)
+{summary paragraph}
+
+**Key entries:** {linked entry IDs}
+**Gaps:** {list of missing knowledge}
+**Health:** {score}/100
+
+### 2. {Theme Name} ...
+
+## Coverage Heatmap
+{matrix}
+
+## Knowledge Gaps
+| Gap | Theme | Type Missing | Suggested Action |
+|-----|-------|-------------|-----------------|
+| No lessons for auth patterns | Security | lesson | Run /learn-decompose on src/auth/ |
+
+## Unlinked Insights
+{lessons.jsonl entries not connected to wiki graph}
+
+## Recommended Actions
+1. {action}: {reason}
+2. ...
+```
+
+### Stage 7: Persist
+1. Write digest file
+2. Append meta-insights to `lessons.jsonl`:
+   - `source: "wiki-digest"`, `category: "technique"`
+   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Phase 2 has no decision entries"
+3. Update `learning-index.json`
+4. Display summary with key findings
+
+**Next-step routing:**
+- Deep dive on a theme → `Skill({ skill: "learn-follow", args: "<wiki-id>" })`
+- Fix graph gaps → `Skill({ skill: "wiki-connect", args: "--fix" })`
+- Decompose code for missing patterns → `Skill({ skill: "learn-decompose", args: "<path>" })`
+- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first |
+| E002 | error | Topic search returned 0 results | Broaden topic or check wiki content |
+| W001 | warning | Too few entries (<5) for meaningful theme clustering | Digest produced but themes may be trivial |
+| W002 | warning | lessons.jsonl not found — skipping cross-reference | Proceed without lesson context |
+| W003 | warning | Some entry bodies failed to load — partial summaries | Note incomplete entries in digest |
+</error_codes>
+
+<success_criteria>
+- [ ] Scope parsed and entries loaded
+- [ ] Baseline health score recorded
+- [ ] Entries clustered into 3-5 semantic themes
+- [ ] Per-theme analysis: summary, key entries, gaps, health
+- [ ] Cross-reference with lessons.jsonl completed
+- [ ] Coverage heatmap generated (type × theme matrix)
+- [ ] Knowledge gaps identified with suggested actions
+- [ ] Digest written to `digest-{slug}-{date}.md`
+- [ ] Meta-insights appended to `lessons.jsonl`
+- [ ] `learning-index.json` updated
+- [ ] No files modified outside `.workflow/learning/`
+- [ ] Summary displayed with key findings and next-step routing
+</success_criteria>