maestro-flow 0.5.3 → 0.5.31

package/workflows/wiki-connect.md

@@ -1,151 +1,151 @@
-# 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, knowhow, note, 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
-
-Gather baseline in parallel via `maestro wiki list --json`, `health`, `orphans`, `hubs --top 10`.
-
-Working state: entry count by type, baseline health score, orphan IDs, hub 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 `knowhow-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
-
-Score 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
-```
-
-Ratios: tag_overlap = shared/max(source,target) tags, BM25 = normalized wiki search, category/type bonuses = 1.0 if match/bridge.
-
-Filter: score >= `--min-similarity`, sort descending, limit to `--max`.
-
----
-
-## 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   knowhow-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: fetch entry, append target-id to `related` list (dedup), update via `maestro wiki update <source-id> --frontmatter`.
-
-After all updates: re-run `maestro wiki health`, report applied/skipped counts and health delta.
-
----
-
-## Stage 6: Persist & Report
-
-1. Write `.workflow/knowhow/KNW-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 as `<spec-entry>` to `.workflow/specs/learnings.md`:
-   - `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/knowhow/KNW-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` |
-
+# 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, knowhow, note, 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
+
+Gather baseline in parallel via `maestro wiki list --json`, `health`, `orphans`, `hubs --top 10`.
+
+Working state: entry count by type, baseline health score, orphan IDs, hub 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 `knowhow-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
+
+Score 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
+```
+
+Ratios: tag_overlap = shared/max(source,target) tags, BM25 = normalized wiki search, category/type bonuses = 1.0 if match/bridge.
+
+Filter: score >= `--min-similarity`, sort descending, limit to `--max`.
+
+---
+
+## 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   knowhow-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: fetch entry, append target-id to `related` list (dedup), update via `maestro wiki update <source-id> --frontmatter`.
+
+After all updates: re-run `maestro wiki health`, report applied/skipped counts and health delta.
+
+---
+
+## Stage 6: Persist & Report
+
+1. Write `.workflow/knowhow/KNW-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 as `<spec-entry>` to `.workflow/specs/learnings.md`:
+   - `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/knowhow/KNW-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` |
+

package/workflows/wiki-digest.md

@@ -1,178 +1,178 @@
-# 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/specs/learnings.md` 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, knowhow, note, 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 by: tag co-occurrence (2+ shared tags), title BM25 similarity, relationship proximity (`related` links), and type sub-clustering.
-
-Per theme: name (dominant tag), entry count/IDs, type distribution, status distribution.
-
----
-
-## 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 knowhow? Issues but no decisions?
-
-### Health Score
-Per-theme health adapted from wiki health formula (entries, connectivity, completeness).
-
----
-
-## Stage 4: Cross-Reference with Knowhow Insights
-
-Search via `maestro wiki search` or parse `.workflow/specs/learnings.md` for keyword matches against each theme. Flag **unlinked insights** — learning entries matching a theme but not referenced by any wiki entry in that theme.
-
-If `learnings.md` 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          ███░░      ░░░░░      █████      ██░░░      ░░░░░
-knowhow       ░░░░░      ████░      ██░░░      ░░░░░      ███░░
-note          █░░░░      ██░░░      ████░      █░░░░      ░░░░░
-issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
-
-Legend: █ = entries exist, ░ = sparse/missing
-```
-
-Empty cells = knowledge gaps. Each gap becomes a candidate for Stage 7.
-
----
-
-## Stage 6: Write Digest
-
-Produce `.workflow/knowhow/KNW-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 knowhow for auth patterns | Security | knowhow | /learn-decompose src/auth/ |
-
-## Unlinked Insights
-{knowhow 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: dedup against `.workflow/issues/issues.jsonl` (same theme + type). If new, append with `type: "knowledge-gap"`, `status: "open"`, `severity: "low"`, `source: "wiki-digest"`, `tags: ["knowledge-gap", "{theme-slug}"]`. Report created count.
-
----
-
-## Stage 8: Persist
-
-1. Write digest file to `.workflow/knowhow/`
-2. Append meta-insights as `<spec-entry>` to `.workflow/specs/learnings.md` (`source="wiki-digest"`, `category="technique"`)
-3. Display summary: scope, entry count, theme count, gap count, created issues (if applicable), report path.
-
----
-
-## 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` |
-
+# 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/specs/learnings.md` 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, knowhow, note, 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 by: tag co-occurrence (2+ shared tags), title BM25 similarity, relationship proximity (`related` links), and type sub-clustering.
+
+Per theme: name (dominant tag), entry count/IDs, type distribution, status distribution.
+
+---
+
+## 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 knowhow? Issues but no decisions?
+
+### Health Score
+Per-theme health adapted from wiki health formula (entries, connectivity, completeness).
+
+---
+
+## Stage 4: Cross-Reference with Knowhow Insights
+
+Search via `maestro wiki search` or parse `.workflow/specs/learnings.md` for keyword matches against each theme. Flag **unlinked insights** — learning entries matching a theme but not referenced by any wiki entry in that theme.
+
+If `learnings.md` 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          ███░░      ░░░░░      █████      ██░░░      ░░░░░
+knowhow       ░░░░░      ████░      ██░░░      ░░░░░      ███░░
+note          █░░░░      ██░░░      ████░      █░░░░      ░░░░░
+issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
+
+Legend: █ = entries exist, ░ = sparse/missing
+```
+
+Empty cells = knowledge gaps. Each gap becomes a candidate for Stage 7.
+
+---
+
+## Stage 6: Write Digest
+
+Produce `.workflow/knowhow/KNW-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 knowhow for auth patterns | Security | knowhow | /learn-decompose src/auth/ |
+
+## Unlinked Insights
+{knowhow 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: dedup against `.workflow/issues/issues.jsonl` (same theme + type). If new, append with `type: "knowledge-gap"`, `status: "open"`, `severity: "low"`, `source: "wiki-digest"`, `tags: ["knowledge-gap", "{theme-slug}"]`. Report created count.
+
+---
+
+## Stage 8: Persist
+
+1. Write digest file to `.workflow/knowhow/`
+2. Append meta-insights as `<spec-entry>` to `.workflow/specs/learnings.md` (`source="wiki-digest"`, `category="technique"`)
+3. Display summary: scope, entry count, theme count, gap count, created issues (if applicable), report path.
+
+---
+
+## 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` |
+