maestro-flow 0.3.12 → 0.3.13

package/workflows/ui-style.md

@@ -23,12 +23,11 @@ Input: <phase> argument (number or slug) OR topic text
 IF argument is a number or matches phase pattern:
   Read .workflow/state.json → state
   artifacts = state.artifacts ?? []
-  IF artifacts.length > 0:
-    art = artifacts.find(a => a.phase === phaseNum)
+  art = artifacts.find(a => a.phase === phaseNum)
+  IF art:
     PHASE_DIR = ".workflow/" + art.path
   ELSE:
-    Find .workflow/phases/{NN}-*/index.json
-    PHASE_DIR = resolved path
+    ERROR "Phase {phaseNum} not found in artifact registry"
   Set SCRATCH_MODE = false
 
 ELSE (topic text — scratch mode):

package/workflows/verify.md

@@ -633,8 +633,8 @@ Fix Plans: {fix_plan_count} generated
 Human Verification: {human_items} items
 
 Files:
-  {phase_dir}/verification.json
-  {phase_dir}/validation.json (if generated)
+  {artifact_dir}/verification.json
+  {artifact_dir}/validation.json (if generated)
 
 Next steps:
   {suggested_next_command}

package/workflows/wiki-connect.md

@@ -0,0 +1,188 @@
+# Wiki Connect Workflow
+
+Knowledge graph link discovery and health improvement. Analyzes the unified wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links.
+
+**Closed-loop**: wiki-connect improves graph → wiki-digest produces better clusters → learn-follow surfaces richer trails.
+
+---
+
+## Prerequisites
+
+- `.workflow/` initialized (`.workflow/state.json` exists)
+- Wiki entries exist (at least 5 for meaningful analysis)
+- `maestro wiki` CLI available
+
+---
+
+## Argument Shape
+
+```
+/wiki-connect                                 → full graph analysis, all types
+/wiki-connect --scope spec                    → limit to spec entries only
+/wiki-connect --scope memory                  → limit to memory entries only
+/wiki-connect --min-similarity 0.5            → raise threshold (default: 0.3)
+/wiki-connect --fix                           → auto-apply top suggestions
+/wiki-connect --max 10                        → limit suggestion count (default: 20)
+/wiki-connect --scope spec --fix --max 5      → combined: fix top 5 spec connections
+```
+
+| Flag | Effect |
+|------|--------|
+| `--scope <type>` | Limit to wiki type: spec, memory, note, lesson, issue. Default: all |
+| `--min-similarity N` | Minimum similarity score 0.0-1.0 (default: 0.3) |
+| `--fix` | Auto-apply top suggestions via `maestro wiki update` |
+| `--max N` | Maximum suggestions to generate (default: 20) |
+
+---
+
+## Stage 1: Load Wiki State
+
+Run these `maestro wiki` commands in parallel to gather baseline:
+
+```bash
+maestro wiki list --json           # all entries with metadata
+maestro wiki health                # composite health score
+maestro wiki orphans               # entries with 0 in/out links
+maestro wiki hubs --top 10         # most-referenced entries
+```
+
+Parse into working state:
+- Entry count and type distribution (spec, memory, note, lesson, issue)
+- Baseline health score (numeric, from health command)
+- Orphan list with entry IDs and titles
+- Hub list with in-degree counts
+
+Apply `--scope` filter if provided — restrict all subsequent analysis to matching type.
+
+---
+
+## Stage 2: Identify Connection Candidates
+
+For each entry, compute potential connections across four dimensions:
+
+### 2a. Orphan Rescue
+For each orphan entry:
+1. `maestro wiki search "<orphan title>"` — BM25 title match
+2. Tag overlap: entries sharing 2+ tags with the orphan
+3. Same category: entries with matching `category` field
+4. Same parent: entries sharing the same `parent` field
+
+### 2b. Missing Bidirectional Links
+Scan forward links (from `maestro wiki graph`):
+- If A → B exists but B → A is missing, suggest adding reverse link
+- Priority: entries where B has low in-degree (would benefit most)
+
+### 2c. Transitive Closure
+For connected pairs A → B and B → C:
+- If A has no link to C, AND A and C share tags or category, suggest A → C
+- Skip if distance >2 hops (avoid over-connecting)
+
+### 2d. Type Bridge
+Detect entries of different types referencing the same concept:
+- e.g., `spec-auth` and `lesson-auth-gotcha` — same domain, different perspectives
+- Use tag overlap + title keyword match to detect shared concepts
+- Only suggest if entries are currently unlinked
+
+---
+
+## Stage 3: Score Candidates
+
+For each candidate connection (source → target):
+
+```
+score = 0.4 × tag_overlap_ratio
+      + 0.3 × title_bm25_similarity
+      + 0.2 × same_category_bonus
+      + 0.1 × type_bridge_bonus
+```
+
+- `tag_overlap_ratio`: shared_tags / max(source_tags, target_tags)
+- `title_bm25_similarity`: normalized BM25 score from `maestro wiki search`
+- `same_category_bonus`: 1.0 if same category, else 0.0
+- `type_bridge_bonus`: 1.0 if different types, else 0.0
+
+Filter: score >= `--min-similarity`
+Sort: descending by score
+Limit: top `--max` entries
+
+---
+
+## Stage 4: Present Suggestions
+
+Display ranked 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) + type bridge
+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 with next-step hints.
+If `--fix`: proceed to Stage 5.
+
+---
+
+## Stage 5: Apply Connections (--fix only)
+
+For each accepted suggestion:
+1. `maestro wiki get <source-id> --json` — get current entry
+2. Extract existing `related` list from frontmatter
+3. Append target-id to `related` if not already present
+4. `maestro wiki update <source-id> --frontmatter '{"related": ["existing...", "new-target"]}'`
+5. Log success/failure per entry
+
+After all updates:
+- Re-run `maestro wiki health` → compute delta
+- Report applied count, skipped count, and health improvement
+
+---
+
+## Stage 6: Persist & Report
+
+1. Write `.workflow/learning/wiki-connections-{YYYY-MM-DD}.md`:
+   - Baseline vs final health scores
+   - All suggestions (applied and unapplied) with scores
+   - Orphan rescue results
+   - Graph structure observations (hub concentration, type distribution)
+   
+2. Append graph insights to `.workflow/learning/lessons.jsonl`:
+   - `source: "wiki-connect"`, `category: "technique"`
+   - e.g., "Auth entries poorly cross-referenced", "Memory entries have highest orphan rate"
+
+3. Display summary:
+```
+== Wiki Connect Complete ==
+Suggestions:  {total} ({applied} applied, {skipped} skipped)
+Health:       {baseline} → {new} ({delta})
+Report:       .workflow/learning/wiki-connections-{date}.md
+```
+
+---
+
+## Next Steps
+
+| Action | Command |
+|--------|---------|
+| Generate knowledge digest | `/wiki-digest <topic>` |
+| Follow-along on orphan | `/learn-follow <wiki-id>` |
+| View full graph | `maestro wiki graph` |
+| Run harvest for new content | `/manage-harvest --recent 7` |
+
+---
+
+## Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Run `/maestro-init` or create wiki content |
+| E002 | error | `maestro wiki` CLI not available | Check maestro installation |
+| W001 | warning | No candidates above threshold | Lower `--min-similarity` or verify graph connectivity |
+| W002 | warning | Some wiki updates failed during `--fix` | Retry failed entries manually |
+| W003 | warning | Health score unchanged after fix | Connections may not affect specific health metrics |

package/workflows/wiki-digest.md

@@ -0,0 +1,221 @@
+# Wiki Digest Workflow
+
+Knowledge synthesis from the wiki knowledge graph. Clusters entries by semantic theme, identifies knowledge gaps, produces coverage heatmaps, and optionally creates knowledge-gap issues.
+
+Unlike `maestro wiki list` which shows raw entries, this workflow synthesizes and interprets the knowledge base — producing curated summaries with gap analysis and recommended actions.
+
+**Closed-loop**: harvest extracts → wiki stores → wiki-digest synthesizes → gap issues → issue pipeline.
+
+---
+
+## Prerequisites
+
+- `.workflow/` initialized
+- Wiki entries exist (at least 5 for meaningful clustering)
+- `maestro wiki` CLI available
+- `.workflow/learning/lessons.jsonl` exists (optional, for cross-reference)
+
+---
+
+## Argument Shape
+
+```
+/wiki-digest                                  → digest entire wiki
+/wiki-digest auth                             → topic-scoped digest
+/wiki-digest --recent 14                      → entries updated in last 14 days
+/wiki-digest --type spec                      → spec entries only
+/wiki-digest --format full                    → detailed per-entry summaries
+/wiki-digest auth --create-issues             → digest + auto-create gap issues
+```
+
+| Flag | Effect |
+|------|--------|
+| `<topic>` | Search wiki for matching entries via BM25 |
+| `--recent N` | Entries updated within last N days |
+| `--type <type>` | Filter by wiki type: spec, memory, note, lesson, issue |
+| `--format brief\|full` | `brief` = compact (default), `full` = detailed per-entry |
+| `--create-issues` | Auto-create knowledge-gap issues in `issues.jsonl` |
+
+---
+
+## Stage 1: Scope & Load
+
+Determine scope from arguments:
+
+| Input | Resolution |
+|-------|-----------|
+| `<topic>` | `maestro wiki search "<topic>" --json` |
+| `--recent N` | `maestro wiki list --json` → filter by updated date |
+| `--type <type>` | `maestro wiki list --type <type> --json` |
+| No args | `maestro wiki list --json` (all entries) |
+
+Load entry metadata: id, title, tags, status, type, related, summary, category.
+
+For `--format full`: also fetch entry bodies via `maestro wiki get <id>` for top entries (by hub score).
+
+Run `maestro wiki health` for baseline health metrics.
+
+---
+
+## Stage 2: Theme Clustering
+
+Group entries into 3-5 semantic themes using:
+
+1. **Tag co-occurrence**: entries sharing 2+ tags → same cluster
+2. **Title BM25 similarity**: entries whose titles match each other's keywords
+3. **Relationship proximity**: entries connected by `related` links → same cluster
+4. **Type sub-clustering**: if all same type, sub-cluster by content/category
+
+Per theme, record:
+- Theme name: dominant tag or keyword
+- Entry count and IDs
+- Type distribution within theme
+- Status distribution (draft/active/completed/archived)
+
+---
+
+## Stage 3: Per-Theme Analysis
+
+For each theme, produce:
+
+### Summary Paragraph
+Synthesize what these entries collectively teach. Focus on the knowledge pattern, not individual details.
+
+### Key Entries
+Top 3-5 most important entries by:
+- Hub score (in-degree from `maestro wiki hubs`)
+- Backlink count (from `maestro wiki backlinks <id>`)
+- Recency (recently updated entries weigh more)
+
+### Gap Detection
+- **Broken links**: `[[references]]` that don't resolve within the theme
+- **Orphans**: entries in this theme with no connections
+- **TODO markers**: entries with `?`, "TODO", "TBD" in title or body
+- **Missing perspectives**: theme has specs but no lessons? Issues but no decisions?
+
+### Health Score
+Per-theme health adapted from wiki health formula (entries, connectivity, completeness).
+
+---
+
+## Stage 4: Cross-Reference with Lessons
+
+1. Read `.workflow/learning/lessons.jsonl`
+2. For each theme, search lessons by keyword match
+3. Identify **unlinked insights**: lessons that match a theme's keywords but are not referenced by any wiki entry in that theme
+4. Flag as "knowledge not yet connected to the graph"
+
+If `lessons.jsonl` not found, skip with W002 warning.
+
+---
+
+## Stage 5: Coverage Heatmap
+
+Build a type × theme matrix showing knowledge density:
+
+```
+              Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
+spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
+memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
+lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
+issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
+
+Legend: █ = entries exist, ░ = sparse/missing
+```
+
+Empty cells = knowledge gaps. Each gap becomes a candidate for Stage 7.
+
+---
+
+## Stage 6: Write Digest
+
+Produce `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.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
+{type × theme matrix}
+
+## Knowledge Gaps
+| Gap | Theme | Type Missing | Suggested Action |
+|-----|-------|-------------|-----------------|
+| No lessons for auth patterns | Security | lesson | /learn-decompose src/auth/ |
+
+## Unlinked Insights
+{lessons.jsonl entries not connected to wiki graph}
+
+## Recommended Actions
+1. {action}: {reason}
+2. ...
+```
+
+---
+
+## Stage 7: Gap → Issue Routing (if --create-issues)
+
+For each knowledge gap from Stage 5:
+1. Dedup: check `.workflow/issues/issues.jsonl` for existing gap with same theme + type
+2. If new, append to `issues.jsonl` using canonical schema (see `~/.maestro/workflows/issue.md` Step 4):
+   - `type`: "knowledge-gap"
+   - `status`: "open"
+   - `severity`: "low"
+   - `source`: "wiki-digest"
+   - `tags`: ["knowledge-gap", "{theme-slug}"]
+3. Report created issue count
+
+---
+
+## Stage 8: Persist
+
+1. Write digest file to `.workflow/learning/`
+2. Append meta-insights to `.workflow/learning/lessons.jsonl`:
+   - `source: "wiki-digest"`, `category: "technique"`
+   - e.g., "Auth knowledge concentrated in specs, lacks lessons"
+3. Display summary:
+
+```
+== Wiki Digest Complete ==
+Scope:     {topic or "all"}
+Entries:   {count}
+Themes:    {theme_count}
+Gaps:      {gap_count} identified
+Issues:    {created_count} created (if --create-issues)
+Report:    .workflow/learning/digest-{slug}-{date}.md
+```
+
+---
+
+## Next Steps
+
+| Action | Command |
+|--------|---------|
+| Deep dive on a theme | `/learn-follow <wiki-id>` |
+| Fix graph connectivity | `/wiki-connect --fix` |
+| Decompose for patterns | `/learn-decompose <path>` |
+| Create missing entries | `maestro wiki create --type <type> --slug <slug>` |
+| Triage gap issues | `/manage-issue list --source wiki-digest` |
+
+---
+
+## Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content |
+| E002 | error | Topic search returned 0 results | Broaden topic or check wiki |
+| W001 | warning | Too few entries (<5) for meaningful clustering | Themes may be trivial |
+| W002 | warning | `lessons.jsonl` not found | Skip cross-reference |
+| W003 | warning | Some entry bodies failed to load | Partial summaries |

package/workflows/wiki-manage.md

@@ -0,0 +1,204 @@
+# Wiki Manage Workflow
+
+Unified wiki knowledge graph management — health monitoring, interactive search, orphan cleanup, and graph statistics.
+
+Complements `wiki-connect.md` (link discovery) and `wiki-digest.md` (synthesis) with day-to-day operational tooling.
+
+---
+
+## Prerequisites
+
+- `.workflow/` initialized
+- Wiki entries exist
+- `maestro wiki` CLI available
+
+---
+
+## Argument Shape
+
+```
+/manage-wiki                                   → health dashboard (default)
+/manage-wiki health                            → health dashboard
+/manage-wiki search auth                       → search for "auth" with follow-up actions
+/manage-wiki cleanup                           → find orphans, broken links, stale entries
+/manage-wiki cleanup --fix                     → auto-fix issues
+/manage-wiki stats                             → graph statistics
+/manage-wiki stats --type spec                 → spec-only statistics
+```
+
+| Flag | Effect |
+|------|--------|
+| `--type <type>` | Filter: spec, memory, note, lesson, issue |
+| `--fix` | Auto-fix issues during cleanup |
+| `--json` | JSON output |
+
+---
+
+## Subcommand: health (default)
+
+### Step 1: Gather Data
+
+Run in parallel:
+```bash
+maestro wiki health
+maestro wiki list --json
+maestro wiki orphans
+maestro wiki hubs --top 5
+```
+
+### Step 2: Render Dashboard
+
+```
+== Wiki Health Dashboard ==
+Score:       {score}/100
+Entries:     {total} ({spec} spec, {memory} memory, {note} note, {lesson} lesson, {issue} issue)
+Broken:      {broken_count} broken links
+Orphans:     {orphan_count} entries with no connections
+Top Hubs:    {hub1} ({degree}), {hub2} ({degree}), ...
+
+{score < 50 ? "⚠ Graph needs attention" : score < 75 ? "Graph is fair" : "Graph is healthy"}
+
+Quick actions:
+  Fix connections:  /wiki-connect --fix
+  Generate digest:  /wiki-digest
+  Cleanup orphans:  /manage-wiki cleanup --fix
+  View full graph:  maestro wiki graph
+```
+
+---
+
+## Subcommand: search <query>
+
+### Step 1: Execute Search
+
+```bash
+maestro wiki search "<query>" --json
+```
+
+### Step 2: Display Results
+
+```
+== Wiki Search: "{query}" ({count} results) ==
+
+#  ID                    Type    Title                        Tags
+1  spec-auth-001         spec    JWT token rotation           auth, security, jwt
+2  memory-auth-flow      memory  Auth module implementation   auth, session
+3  note-auth-review      note    Auth code review findings    auth, review
+
+Actions:
+  View:    maestro wiki get <id>
+  Links:   maestro wiki backlinks <id>
+  Follow:  /learn-follow <id>
+  Connect: /wiki-connect --scope <type>
+```
+
+### Step 3: Interactive Follow-up
+
+If not `--json`: offer to view an entry by number selection.
+
+---
+
+## Subcommand: cleanup
+
+### Step 1: Scan Issues
+
+Gather:
+```bash
+maestro wiki health          # baseline
+maestro wiki orphans --json  # orphaned entries
+maestro wiki graph           # broken links from graph structure
+```
+
+### Step 2: Categorize Issues
+
+| Issue Type | Detection | Auto-fix Action |
+|-----------|-----------|----------------|
+| Broken links | Forward link target doesn't exist | Remove broken link from frontmatter |
+| Orphans | No in/out links | Suggest connections via BM25 title match |
+| Stale entries | No updates in 90+ days, status=draft | Flag for review |
+| Empty body | Entry exists but body is empty/placeholder | Flag for review |
+
+### Step 3: Display Issues
+
+```
+== Wiki Cleanup Scan ==
+Baseline health: {score}/100
+
+Issues found:
+  Broken links:   {count}
+  Orphans:        {count}
+  Stale drafts:   {count}
+  Empty bodies:   {count}
+
+{list of issues with entry IDs and descriptions}
+```
+
+### Step 4: Apply Fixes (--fix only)
+
+For each fixable issue:
+1. Broken links: `maestro wiki update <id> --frontmatter '{"related": [filtered_list]}'`
+2. Orphans: run mini wiki-connect for each orphan (BM25 search + tag match)
+3. Stale/empty: flag but don't auto-delete (too destructive)
+
+Report delta:
+```
+== Cleanup Complete ==
+Fixed:     {fixed_count} issues
+Remaining: {remaining_count} (manual review needed)
+Health:    {old_score} → {new_score} ({delta})
+```
+
+---
+
+## Subcommand: stats
+
+### Step 1: Gather Data
+
+```bash
+maestro wiki list --json
+```
+
+### Step 2: Compute Statistics
+
+- **Type distribution**: count per type (spec, memory, note, lesson, issue)
+- **Tag frequency**: top 20 most-used tags
+- **Category distribution**: entries per category (for specs)
+- **Connectivity**: average in-degree, average out-degree, max hub size
+- **Growth**: entries created per week (from timestamps)
+
+### Step 3: Display
+
+```
+== Wiki Statistics ==
+
+Type Distribution:
+  spec      ████████████████  32 (40%)
+  memory    ████████          16 (20%)
+  note      ██████████        20 (25%)
+  lesson    ████              8 (10%)
+  issue     ██                4 (5%)
+  Total:    80
+
+Top Tags:
+  auth (12), performance (8), error-handling (7), testing (6), ...
+
+Connectivity:
+  Avg in-degree:  2.3
+  Avg out-degree: 1.8
+  Hub:            spec-auth (in=12)
+
+Growth (last 4 weeks):
+  Week 1: +5  |  Week 2: +8  |  Week 3: +3  |  Week 4: +12
+```
+
+---
+
+## Error Codes
+
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | fatal | `.workflow/` not initialized | Run `/maestro-init` |
+| E002 | fatal | No wiki entries found | Create wiki content first |
+| E003 | error | Invalid subcommand | Valid: health, search, cleanup, stats |
+| W001 | warning | Health score below 50 | Run `/wiki-connect --fix` |
+| W002 | warning | Cleanup had partial failures | Retry manually |