pi-maestro-flow 0.2.0 → 0.3.1

package/workflows/wiki-connect.md

@@ -0,0 +1,153 @@
+# 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`.
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: graph operations (`orphans`, `hubs --top 10`) — use the `maestro wiki` CLI to compute in-degree and orphan sets.
+
+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

@@ -0,0 +1,180 @@
+# 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:
+- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: Hub score (in-degree from `maestro wiki hubs`)
+- MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: 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; mark digest cross-reference as [LOW CONFIDENCE] (learnings.md missing).
+
+---
+
+## 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. ...
+```
+
+---
+
+GATE Stage 6→7: gaps identified BEFORE issue routing; BLOCKED if no gaps identified in Stage 5
+
+## 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` |
+

package/workflows/wiki-manage.md

@@ -0,0 +1,113 @@
+# 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, knowhow, note, issue |
+| `--fix` | Auto-fix issues during cleanup |
+| `--json` | JSON output |
+
+---
+
+## Subcommand: health (default)
+
+### Step 1: Gather Data
+
+Run in parallel: `maestro wiki health`, `list --json`, `orphans`, `hubs --top 5`.
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: graph operations (`orphans`, `hubs --top 5`) — use the `maestro wiki` CLI to compute orphan sets and hub in-degree.
+
+### Step 2: Render Dashboard
+
+Display: health score, entry counts by type, broken links, orphan count, top hubs. Include health status message and quick-action commands (`/wiki-connect --fix`, `/wiki-digest`, `/manage-wiki cleanup --fix`, `maestro wiki graph`).
+
+> **Scope split (complementary, not conflicting):** `/wiki-connect --fix` repairs/augments `related` links between existing entries (no deletion). `/manage-wiki cleanup --fix` deletes/flags orphans and removes broken-link entries from frontmatter. Run `wiki-connect` first to maximize link recovery, then `cleanup` to handle the true residual orphans.
+
+---
+
+## Subcommand: search <query>
+
+### Step 1: Execute Search
+
+```bash
+maestro wiki search "<query>" --json
+```
+
+### Step 2: Display Results
+
+Show table of results (ID, type, title, tags) with action hints: `maestro wiki get <id>`, `backlinks <id>`, `/learn-follow <id>`, `/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 baseline via `maestro wiki health`, `orphans --json`, `graph`.
+
+MANDATORY, NOT SUBSTITUTABLE by manual Read/Grep: graph operations (`orphans --json`, `graph`) — use the `maestro wiki` CLI to compute orphans and graph topology.
+
+### 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
+
+Show baseline health, issue counts by type, and entry-level details.
+
+### Step 4: Apply Fixes (--fix only)
+
+Broken links: remove from frontmatter via `maestro wiki update`. Orphans: mini wiki-connect (BM25 + tag match). Stale/empty: flag only (no auto-delete).
+
+Report: fixed count, remaining count, health delta.
+
+---
+
+## Subcommand: stats
+
+### Step 1: Gather Data
+
+```bash
+maestro wiki list --json
+```
+
+### Step 2: Compute & Display Statistics
+
+Compute: type distribution (count/%), top 20 tags, category distribution (specs), connectivity (avg in/out-degree, max hub), growth (entries/week).
+
+Display as bar charts and summary tables.
+