maestro-flow 0.4.26 → 0.5.0

package/.agents/skills/manage-codebase-refresh/SKILL.md

@@ -1,62 +0,0 @@
----
-name: manage-codebase-refresh
-description: Refresh codebase docs from recent changes
-argument-hint: "[--since <date>] [--deep]"
-allowed-tools:
-  - read_file
-  - write_file
-  - edit_file
-  - shell
-  - find_files
-  - search
-  - delegate_subagent
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-
-<purpose>
-Incrementally refresh .workflow/codebase/ documentation based on changes since the last rebuild or refresh. Detects which files have changed (via git diff), identifies which codebase docs are affected, selectively re-runs mapper agents on those areas only, and updates timestamps. Much faster than a full rebuild for ongoing maintenance.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/codebase-refresh.md
-</required_reading>
-
-<context>
-$ARGUMENTS -- optional flags.
-
-**Flags:**
-- `--since <date>` -- Override change detection window (ISO date or relative like "3d")
-- `--deep` -- Force deeper re-scan even for files with minor changes
-
-**State files:**
-- `.workflow/` -- must be initialized
-- `.workflow/codebase/` -- must contain existing docs (from prior rebuild)
-- `.workflow/codebase/doc-index.json` -- documentation index with timestamps
-- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph (optional, for KG impact analysis)
-- `.workflow/state.json` -- contains `codebase_last_rebuilt` timestamp
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/codebase-refresh.md' completely.
-</execution>
-
-<error_codes>
-| Code | Meaning                                                  |
-|------|----------------------------------------------------------|
-| E001 | .workflow/ not initialized                               |
-| E002 | No codebase/ docs exist, use codebase-rebuild instead    |
-| W001 | No changes detected since last refresh                   |
-</error_codes>
-
-<success_criteria>
-- [ ] Changed files detected via git diff since last refresh
-- [ ] Affected documentation entries identified from doc-index.json
-- [ ] KG impact analysis run (if knowledge-graph.json exists): `maestro kg diff-wiki --json`
-- [ ] Affected wiki entries flagged with warnings (if any)
-- [ ] Only affected docs refreshed (selective mapper re-run)
-- [ ] doc-index.json timestamps updated per affected entry
-- [ ] state.json updated with codebase_last_refreshed timestamp
-- [ ] Next step routing: `/manage-status` or `/spec-load` to use updated docs
-</success_criteria>

package/.agents/skills/manage-learn/SKILL.md

@@ -1,67 +0,0 @@
----
-name: manage-learn
-description: Capture and search learning insights and tips
-argument-hint: "[<text> | tip <text> | list | search | show <id>] [--category <cat>] [--tag t1,t2] [--phase N]"
-allowed-tools:
-  - read_file
-  - write_file
-  - edit_file
-  - shell
-  - find_files
-  - search
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-<purpose>
-Unified atomic knowledge capture for the workflow learning library. Captures two types of knowledge:
-- **Insights**: Timeless "eureka moment" entries (patterns, gotchas, techniques) — the default mode
-- **Tips**: Quick contextual notes for cross-session recovery (formerly in `manage-knowhow-capture tip`)
-
-Both types are stored in `.workflow/specs/learnings.md` as `<spec-entry>` blocks with auto-detected phase linkage and keyword-based category inference. Tips are distinguished by `source: "tip"` and implicitly tagged `tip`. Same store as retrospective output, so search and list see the entire knowledge corpus.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/learn.md
-</required_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-**Modes (auto-detected from first token):**
-- `"<insight text>"` (or any non-keyword text) → insight capture mode
-- `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
-- `list` → list recent entries (default 20)
-- `search <query>` → `maestro spec load --category learning` or text search across `.workflow/specs/learnings.md`
-- `show <INS-id>` → full detail with phase context
-- empty → ask_user to prompt for text
-
-Flags, storage paths, and shared store rationale defined in workflow learn.md.
-</context>
-
-<execution>
-Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Stage |
-|------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
-| E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
-| E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in `.workflow/specs/learnings.md` | show |
-| W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
-</error_codes>
-
-<success_criteria>
-- [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `<spec-entry>` block appended to `.workflow/specs/learnings.md` with all required fields
-- [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
-- [ ] Capture: category inference produces a sensible default when `--category` absent
-- [ ] List: filters apply, output sorted newest-first, default limit 20
-- [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
-- [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/specs/learnings.md` and `.workflow/knowhow/`
-- [ ] Confirmation banner displayed with INS-id and next-step hints
-- [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
-</success_criteria>

package/.agents/skills/wiki-connect/SKILL.md

@@ -1,64 +0,0 @@
----
-name: wiki-connect
-description: Find and link hidden connections in wiki graph
-argument-hint: "[--scope <type>] [--min-similarity N] [--fix] [--max N]"
-allowed-tools:
-  - read_file
-  - write_file
-  - shell
-  - find_files
-  - search
-  - delegate_subagent
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-<required_reading>
-@~/.maestro/workflows/wiki-connect.md
-</required_reading>
-
-<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, storage paths, and CLI commands defined in workflow wiki-connect.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/wiki-connect.md' completely (Stages 1-6).
-
-**Next-step routing:**
-- Generate knowledge digest → `/wiki-digest <topic>`
-- Follow-along on orphan → `/learn-follow <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 `/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 `specs/learnings.md` as `<spec-entry>` blocks
-- [ ] No unintended entry modifications (only `related` field changed)
-- [ ] Summary displayed with next-step routing
-</success_criteria>

package/.agents/skills/wiki-digest/SKILL.md

@@ -1,70 +0,0 @@
----
-name: wiki-digest
-description: Generate wiki digest with theme clustering and gap analysis
-argument-hint: "[<topic>|--recent N] [--type <type>] [--format brief|full]"
-allowed-tools:
-  - read_file
-  - write_file
-  - shell
-  - find_files
-  - search
-  - delegate_subagent
-  - ask_user
----
-<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
-
-<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>
-
-<required_reading>
-@~/.maestro/workflows/wiki-digest.md
-</required_reading>
-
-<deferred_reading>
-- @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
-</deferred_reading>
-
-<context>
-Arguments: $ARGUMENTS
-
-Flags, scope resolution, storage paths, and CLI commands defined in workflow wiki-digest.md.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/wiki-digest.md' completely (Stages 1-8).
-
-**Next-step routing:**
-- Deep dive on a theme → `/learn-follow <wiki-id>`
-- Fix graph gaps → `/wiki-connect --fix`
-- Decompose code for missing patterns → `/learn-decompose <path>`
-- Create missing entries → `maestro wiki create --type <type> --slug <slug>`
-- Triage gap issues → `/manage-issue list --source wiki-digest`
-</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 | specs/learnings.md not found — skipping cross-reference | Proceed without knowhow 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 specs/learnings.md completed
-- [ ] Coverage heatmap generated (type × theme matrix)
-- [ ] Knowledge gaps identified with suggested actions
-- [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
-- [ ] Digest written to `KNW-digest-{slug}-{date}.md`
-- [ ] Meta-insights appended to `specs/learnings.md` as `<spec-entry>` blocks
-- [ ] No files modified outside `.workflow/knowhow/` and `.workflow/issues/` (issues only when `--create-issues`)
-- [ ] Summary displayed with key findings and next-step routing
-</success_criteria>

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

@@ -1,159 +0,0 @@
----
-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 `.workflow/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
-- `.workflow/specs/learnings.md` — appended `<spec-entry>` blocks (source: retro-git / retro-decision)
-
-**Storage read**: git history, `.workflow/state.json`, prior `KNW-retro-*.json`, `.workflow/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: .workflow/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 .workflow/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, .workflow/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
-- [ ] .workflow/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>

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

@@ -1,142 +0,0 @@
----
-name: maestro-learn
-description: Route learning intent to learn-* commands
-argument-hint: <intent> [-y] [--dry-run] [--chain <name>]
-allowed-tools:
-  - ask_question
-  - define_subagent
-  - grep_search
-  - invoke_subagent
-  - manage_subagents
-  - run_command
-  - send_message
-  - view_file
-  - write_to_file
----
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
-
-Executes commands sequentially via Skill() with session tracking.
-</purpose>
-
-<context>
-$ARGUMENTS — user learning intent text, or flags.
-
-**Flags:**
-- `-y` / `--yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain (bypass intent detection)
-
-**Available learn commands:**
-| Command | Purpose |
-|---------|---------|
-| `learn-follow` | Guided reading with forcing questions, pattern extraction |
-| `learn-investigate` | Hypothesis-driven question investigation |
-| `learn-decompose` | 4-dimension parallel pattern extraction |
-| `learn-second-opinion` | Multi-perspective review/challenge/consult |
-| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
-
-**Available chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer a "how/why" question |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Storage:**
-- `.workflow/knowhow/.maestro-learn/{session_id}/status.json` — Session tracking
-- All learn command outputs go to `.workflow/knowhow/`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
-
-**If `--chain` specified:** validate against known chains, jump to Step 2.
-
-**Intent routing table** (match first token or keywords):
-
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| Wiki ID (`type-slug` pattern) | `follow` |
-| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
-| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
-| pattern, decompose, catalog, 分解, 模式 | `decompose` |
-| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
-| retro, git, commit, decision, 回顾 | `retro` |
-| thorough, deep, 全面, 深入 | `deep-understand` |
-
-**If no match:** present menu via ask_question:
-```
-What would you like to do?
-1. Read through code/docs → follow
-2. Investigate a question → investigate
-3. Find patterns in code → decompose
-4. Get a second opinion → second-opinion
-5. Retrospective → retro
-```
-
-Max 1 clarification round. If still unclear: error.
-
-### Step 2: Resolve Target & Build Args
-
-- File path → pass directly
-- Wiki ID → pass directly
-- Topic string → pass as quoted argument
-- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
-
-**Chain → command mapping:**
-```
-follow          → Skill("learn-follow", "{target} {flags}")
-investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
-decompose       → Skill("learn-decompose", "{target} {flags}")
-second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
-retro           → Skill("learn-retro", "{flags}")
-deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
-pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
-```
-
-### Step 3: Confirm & Execute
-
-**If `--dry-run`:** display chain plan and exit.
-
-**If not `-y`:** show plan, ask for confirmation.
-
-**Execute:**
-1. Create session dir: `.workflow/knowhow/.maestro-learn/learn-{timestamp}/`
-2. Write `status.json` with chain steps
-3. Execute each step via `Skill()`:
-   - On success: mark completed, continue
-   - On failure (interactive): ask retry/skip/abort
-   - On failure (auto): skip and continue
-4. Display session summary with artifact list and next-step suggestion
-
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent provided | Provide a learning goal or use --chain |
-| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
-| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous between commands | Present options |
-| W002 | warning | Chain step completed with warnings | Log and continue |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain (or --chain validated)
-- [ ] Target resolved and arguments assembled
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed via Skill()
-- [ ] Error handling: retry/skip/abort per step
-- [ ] Session summary displayed with next-step routing
-- [ ] No files modified outside `.workflow/knowhow/`
-</success_criteria>