maestro-flow 0.3.43 → 0.3.45

package/workflows/learn.md

@@ -3,8 +3,8 @@
 Atomic insight capture, search, and retrieval. Lightweight gstack-style "eureka moment" log that complements the retrospective workflow: where retrospective extracts insights from completed phases in bulk, `manage-learn` captures one insight at a time during active work.
 
 Storage:
-- `.workflow/learning/lessons.jsonl` — append-only JSONL row per insight (shared with retrospective output)
-- `.workflow/learning/learning-index.json` — searchable index
+- `.workflow/specs/learnings.md` — append-only container of `<spec-entry>` sub-entries (shared with retrospective output)
+- Auto-indexed by WikiIndexer (no manual index required)
 
 **Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
 
@@ -15,7 +15,7 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 ## Prerequisites
 
 - `.workflow/` initialized (`.workflow/state.json` exists). If missing, error E001.
-- The `learning/` directory and its files are created on first use; do not require them to exist upfront.
+- The `specs/` directory and `learnings.md` are created on first use; do not require them to exist upfront.
 
 ---
 
@@ -23,17 +23,17 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 
 ```
 /manage-learn "<insight text>"                                  → capture, infer category, auto-link phase
-/manage-learn "<insight>" --category pattern --tag auth,jwt    → capture with explicit category and tags
+/manage-learn "<insight>" --category pattern --keywords auth,jwt → capture with explicit category and keywords
 /manage-learn list                                              → show recent 20 insights
-/manage-learn list --tag auth                                   → filtered list
-/manage-learn search <query>                                    → text search across lessons.jsonl
+/manage-learn list --keywords auth                              → filtered list
+/manage-learn search <query>                                    → search via maestro wiki search
 /manage-learn show <INS-id>                                     → full insight + linked phase context
 ```
 
 | Flag | Effect |
 |------|--------|
 | `--category <name>` | One of: pattern, antipattern, decision, tool, gotcha, technique, tip. Default: inferred (tip mode defaults to `tip`). |
-| `--tag t1,t2` | Comma-separated tags. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`. |
+| `--keywords t1,t2` | Comma-separated keywords. Insight mode implicitly adds `manual`, tip mode implicitly adds `tip`. |
 | `--phase <N>` | Override auto-detected phase link. Use `--phase 0` to force "no phase". |
 | `--confidence <level>` | high / medium / low. Default: medium (insight), low (tip). |
 | `--lens <name>` | Filter by retrospective lens: technical, process, quality, decision, git (list/search only). |
@@ -46,7 +46,7 @@ This workflow does NOT spawn agents or call CLI tools. It is a thin file operati
 ```
 Verify .workflow/ exists (else E001). Route by first token:
   "list" → list | "search" → search (next token = query) | "show" → show (next token = INS-id)
-  "tip"  → tip capture (source="tip", category="tip", confidence="low", implicit tag "tip")
+  "tip"  → tip capture (source="tip", category="tip", confidence="low", implicit keyword "tip")
   else   → capture mode (full quoted text = insight body)
 Empty args → AskUserQuestion. Invalid --category → E002.
 ```
@@ -58,15 +58,27 @@ Empty args → AskUserQuestion. Invalid --category → E002.
 ### Step 2.1: Bootstrap storage
 
 ```bash
-LEARN_DIR=".workflow/learning"
-LESSONS_FILE="$LEARN_DIR/lessons.jsonl"
-INDEX_FILE="$LEARN_DIR/learning-index.json"
+SPECS_DIR=".workflow/specs"
+INSIGHTS_FILE="$SPECS_DIR/learnings.md"
 
-mkdir -p "$LEARN_DIR"
-touch "$LESSONS_FILE"
+mkdir -p "$SPECS_DIR"
 
-if [ ! -f "$INDEX_FILE" ]; then
-  echo '{"entries":[],"_metadata":{"created":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","version":"1.0"}}' > "$INDEX_FILE"
+if [ ! -f "$INSIGHTS_FILE" ]; then
+  cat > "$INSIGHTS_FILE" << 'EOF'
+---
+title: "Learning Insights"
+type: spec
+roles: [implement]
+tags: [insights, learning]
+created: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+---
+# Learning Insights
+
+Atomic insights captured during active work.
+
+## Entries
+
+EOF
 fi
 ```
 
@@ -102,32 +114,33 @@ Simple keyword heuristics — no LLM call. Match the insight text (lowercased) a
 
 First match wins. If nothing matches, category = `technique`.
 
-### Step 2.5: Build row
+### Step 2.5: Build spec-entry
 
 ```
-row = {
-  id: "INS-{hex}",
-  phase: phase,
-  phase_slug: phase_slug,
-  lens: null,                  // null for manual capture (only retrospective sets this)
-  category: category,
-  title: first 80 chars of insight text (truncated on word boundary),
-  summary: full insight text,
-  confidence: --confidence value or "medium",
-  tags: parsed --tag values + ["manual"],
-  evidence_refs: [],           // empty for manual capture
-  routed_to: "none",
-  routed_id: null,
-  source: "manual",
-  captured_at: now ISO 8601 UTC
-}
+entry = <spec-entry
+  category="{category}"
+  keywords="{category},{parsed --keywords values joined by comma}"
+  date="{YYYY-MM-DD}"
+  id="INS-{hex}"
+  source="manual"
+>
+
+### {title: first 80 chars of insight text, truncated on word boundary}
+
+{full insight text}
+
+- **Phase**: {phase or "none"} ({phase_slug or "—"})
+- **Confidence**: {--confidence value or "medium"}
+- **Tags**: {parsed --keywords values + ["manual"]}
+
+</spec-entry>
 ```
 
 ### Step 2.6: Persist
 
-Append row as single JSON line to `.workflow/learning/lessons.jsonl`.
+Append the `<spec-entry>` block to `.workflow/specs/learnings.md`.
 
-Update `.workflow/learning/learning-index.json` — append an index entry mirroring key row fields: `id`, `type:"insight"`, `timestamp`, `file:"lessons.jsonl"`, `summary` (=title), `tags`, `lens`, `category`, `phase`, `phase_slug`, `confidence`, `routed_to:"none"`, `routed_id:null`.
+WikiIndexer auto-indexes the entry — no manual index update required.
 
 ### Step 2.7: Confirmation banner
 
@@ -139,12 +152,12 @@ Display: ID, category, confidence, tags, phase (+slug if present), title, file p
 
 ### Step 3.1: Read entries
 
-Read `.workflow/learning/learning-index.json`. Filter by `--tag`, `--category`, `--phase`, `--lens` flags. Sort by timestamp descending. Limit to 20 (or `--limit N`).
+Query via `maestro wiki list --type knowhow --role implement --json`. Filter by `--keywords`, `--category`, `--phase`, `--lens` flags. Sort by timestamp descending. Limit to 20 (or `--limit N`).
 
 ### Step 3.2: Display table
 
 ```
-=== LEARNING INSIGHTS ({shown}/{total}) ===
+=== KNOWHOW INSIGHTS ({shown}/{total}) ===
 
   ID              Category    Phase   Conf   Tags                 Title
   ──────────────  ──────────  ──────  ─────  ───────────────────  ────────────────────────────
@@ -174,9 +187,9 @@ Capture your first: Skill({ skill: "manage-learn", args: "\"...\"" })
 
 Next token after "search". Empty → AskUserQuestion.
 
-### Step 4.2: Scan lessons.jsonl
+### Step 4.2: Search via wiki
 
-Case-insensitive search across each row's `title`, `summary`, `tags`, `category`, `lens`. Rank matches: title match +3, tags +2, summary +1. Sort by rank desc, then captured_at desc.
+Execute `maestro wiki search "<query>" --type knowhow --json`. Results are ranked by BM25 relevance. Sort by rank desc, then date desc.
 
 ### Step 4.3: Display results
 
@@ -204,45 +217,44 @@ List all: Skill({ skill: "manage-learn", args: "list" })
 
 ## Stage 5: show mode
 
-### Step 5.1: Locate row
+### Step 5.1: Locate entry
 
-Find row matching target INS-id in `lessons.jsonl`. Missing arg → E003. Not found → E004.
+Find `<spec-entry>` matching target INS-id in `learnings.md`. Missing arg → E003. Not found → E004.
 
 ### Step 5.2: Resolve linked phase context (if any)
 
-If `row.phase_slug` set: look up phase directory from `state.json` artifacts, read its `index.json` for title/status, check for `retrospective.md`.
+If `entry.phase_slug` set (parsed from entry content): look up phase directory from `state.json` artifacts, read its `index.json` for title/status, check for `retrospective.md`.
 
 ### Step 5.3: Resolve routed artifact (if any)
 
-Map `routed_to` → path: `spec` → `.workflow/specs/{id}`, `issue` → `.workflow/issues/issues.jsonl#{id}`, `note` → `.workflow/knowhow/{id}.md`.
+Map `routed_to` → path: `spec` → `.workflow/specs/{id}`, `issue` → `.workflow/issues/issues.jsonl#{id}`, `knowhow` → `.workflow/knowhow/{id}.md`.
 
 ### Step 5.4: Display
 
 ```
 =========================================
-  INSIGHT: {row.id}
-  CATEGORY: {row.category}
-  CONFIDENCE: {row.confidence}
-  SOURCE: {row.source}{IF row.lens: " (" + row.lens + " lens)"}
+  INSIGHT: {entry.id}
+  CATEGORY: {entry.category}
+  CONFIDENCE: {entry.confidence}
+  SOURCE: {entry.source}{IF entry.lens: " (" + entry.lens + " lens)"}
 =========================================
 
-CAPTURED:    {row.captured_at}
-PHASE:       {row.phase or "none"}{IF phase_slug: " (" + phase_slug + ")"}
-TAGS:        {row.tags joined by ", "}
+CAPTURED:    {entry.date}
+PHASE:       {entry.phase or "none"}{IF phase_slug: " (" + phase_slug + ")"}
+TAGS:        {entry.keywords}
 
 TITLE:
-  {row.title}
+  {entry.title}
 
 SUMMARY:
-  {row.summary}
+  {entry.content}
 
 EVIDENCE:
-  {FOR ref in row.evidence_refs:} - {ref}{END FOR}
-  {OR "(none — manual capture)"}
+  {parsed from entry content, or "(none — manual capture)"}
 
 ROUTED:
-  Target: {row.routed_to}
-  ID:     {row.routed_id or "—"}
+  Target: {entry.routed_to or "none"}
+  ID:     {entry.routed_id or "—"}
   Path:   {routed_path or "—"}
 
 {IF phase_context:}
@@ -259,7 +271,7 @@ PHASE CONTEXT:
 
 | Workflow | Relationship |
 |----------|--------------|
-| `quality-retrospective` | Producer. Writes insights into the same `lessons.jsonl` with `source: "retrospective"` and a populated `lens` field. |
-| `manage-knowhow-capture` | Sibling. Captures session state for recovery; `learn` captures timeless insights. They share the JSONL+index pattern but live in different directories so retrieval semantics stay clean. |
+| `quality-retrospective` | Producer. Appends `<spec-entry>` to the same `specs/learnings.md` with `source: "retrospective"` and a populated `lens` field. |
+| `manage-knowhow-capture` | Sibling. Captures session state for recovery; `learn` captures timeless insights. Both write to `.workflow/knowhow/` with different prefixes. |
 | `phase-transition` | Reader (informally). Phase-transition's free-form `.workflow/specs/learnings.md` is a distinct file with a different audience; do not merge them. |
-| `maestro-plan` | Future consumer. Should query `lessons.jsonl` filtered by tag/lens/category to inform planning decisions. (Out of scope for this command.) |
+| `maestro-plan` | Future consumer. Should query via `maestro wiki search` or `maestro wiki list --type knowhow --role implement` to inform planning decisions. (Out of scope for this command.) |

package/workflows/milestone-complete.md

@@ -41,7 +41,7 @@ Archive completed milestone, move artifacts to history, and prepare for next.
 ## Step 2.5: Load Existing Learnings
 
 ```
-existing_learnings = maestro spec load --category learning
+existing_learnings = maestro spec load --category coding
 ```
 
 Check existing entries to avoid duplicates when appending in Step 3.

package/workflows/retrospective.md

@@ -1,8 +1,8 @@
 # Retrospective Workflow
 
-Multi-lens 复盘 of completed phase artifacts. Consumes existing execution outputs (verification.json, review.json, issues.jsonl, .summaries/, state.json, uat.md, plan.json) and routes distilled insights into the spec / note / issue / lessons stores.
+Multi-lens 复盘 of completed phase artifacts. Consumes existing execution outputs (verification.json, review.json, issues.jsonl, .summaries/, state.json, uat.md, plan.json) and routes distilled insights into the spec / note / issue / knowhow stores.
 
-This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and lesson rows. It never modifies existing phase artifacts.
+This is a **post-execution analysis** workflow. It reads only — until the routing stage, where it writes new spec stubs, issue rows, memory entries, and knowhow entries. It never modifies existing phase artifacts.
 
 ---
 
@@ -304,24 +304,24 @@ Accept all? [Y/n/i for individual]
 
 #### Target: spec
 
-Route spec-routed insights as `<spec-entry>` entries into the appropriate category file. Map insight type to category:
-- `pattern` / `convention` → `coding`
-- `adr-candidate` / architecture → `arch`
-- quality-related → `quality`
+Route spec-routed insights as `<spec-entry>` entries into the appropriate target file. Map insight type to roles:
+- `pattern` / `convention` → `implement`
+- `adr-candidate` / architecture → `plan`
+- quality-related → `review`
 
 ```
-Map insight type → category → target file:
-  pattern/convention → coding → coding-conventions.md
-  adr-candidate/architecture → arch → arch-decisions.md
-  quality-related → quality → quality-conventions.md
+Map insight type → roles → target file:
+  pattern/convention → implement → coding-conventions.md
+  adr-candidate/architecture → plan → arch-decisions.md
+  quality-related → review → quality-conventions.md
 
 Append <spec-entry> to .workflow/specs/{target_file} with:
-  category, keywords (3-5 extracted from title+summary), date, source="retrospective"
+  roles, keywords (3-5 extracted from title+summary), date, source="retrospective"
   Body: insight title, summary, evidence refs, phase/lens/INS_id/confidence metadata
 
-Create target file with category frontmatter if it does not exist.
+Create target file with roles frontmatter if it does not exist.
 
-insight.routed_id = "{category_file}#INS-{INS_id}"
+insight.routed_id = "{target_file}#INS-{INS_id}"
 ```
 
 #### Target: note
@@ -369,26 +369,38 @@ After all routings complete, re-write `retrospective.json` with the `routed_id`
 
 ---
 
-## Stage 7: persist_lessons
+## Stage 7: persist_insights
 
-Append every distilled insight (regardless of routing target, including `routed_to: "none"`) to the lessons store.
+Append every distilled insight (regardless of routing target, including `routed_to: "none"`) to the knowhow store.
 
 ### Bootstrap
 
 ```
-Ensure .workflow/learning/lessons.jsonl and learning-index.json exist.
-Initialize learning-index.json with {"entries":[],"_metadata":{"created":"...","version":"1.0"}} if new.
+Ensure .workflow/specs/ exists and learnings.md exists.
+Create learnings.md with frontmatter (title, type: spec, roles: [implement]) if new.
 ```
 
-### Append rows
+### Append entries
 
-For each insight in `distilled_insights`, append a JSON line to `.workflow/learning/lessons.jsonl` with fields:
-`{ id, phase, phase_slug, lens, category, title, summary, confidence, tags, evidence_refs, routed_to, routed_id, source: "retrospective", captured_at }`
+For each insight in `distilled_insights`, append a `<spec-entry>` to `.workflow/specs/learnings.md`:
 
-### Update index
+```html
+<spec-entry category="{insight.category}" keywords="{insight.tags joined by comma}" date="{YYYY-MM-DD}" id="{insight.id}" source="retrospective">
 
-Append an entry to `.workflow/learning/learning-index.json` entries[] for each new insight:
-`{ id, type: "insight", timestamp, file: "lessons.jsonl", summary (80 chars), tags, lens, category, phase, phase_slug, confidence, routed_to, routed_id }`
+### {insight.title}
+
+{insight.summary}
+
+- **Phase**: {phase} ({phase_slug})
+- **Lens**: {insight.lens}
+- **Confidence**: {insight.confidence}
+- **Evidence**: {insight.evidence_refs}
+- **Routed to**: {insight.routed_to} ({insight.routed_id or "—"})
+
+</spec-entry>
+```
+
+WikiIndexer auto-indexes each entry — no manual index update required.
 
 ### Backward-compat append to specs/learnings.md
 
@@ -399,7 +411,7 @@ Append each insight to .workflow/specs/learnings.md as <spec-entry> with:
   category="learning", keywords (3-5 extracted), date, source="retrospective"
   Body: title, summary, phase/lens/INS_id metadata
 
-Create file with category frontmatter + "## Entries" header if it does not exist.
+Create file with roles frontmatter + "## Entries" header if it does not exist.
 ```
 
 ---
@@ -409,12 +421,12 @@ Create file with category frontmatter + "## Entries" header if it does not exist
 Print confirmation banner and route the user.
 
 ```
-Print banner: phase, lenses run, insight count, routing summary (spec/note/issue/lesson counts with target paths), output file paths.
+Print banner: phase, lenses run, insight count, routing summary (spec/note/issue/knowhow counts with target paths), output file paths.
 
 Suggested next steps:
   manage-status                              — Review project state
   manage-issue list --source retrospective   — Triage created issues
-  manage-learn list                          — Browse the lessons library
+  manage-learn list                          — Browse the insights library
   maestro-milestone-audit                    — Audit milestone if all phases done
 ```
 
@@ -484,39 +496,21 @@ If `mode == "range"` or `--all`, loop Stages 3-8 per phase, then print aggregate
 }
 ```
 
-### lessons.jsonl row
+### spec-entry (in specs/learnings.md)
 
-One JSON object per line:
+```html
+<spec-entry category="coding" keywords="pattern,auth,jwt,security" date="2026-04-11" id="INS-a1b2c3d4" source="retrospective">
 
-```json
-{"id":"INS-a1b2c3d4","phase":1,"phase_slug":"01-auth","lens":"technical","category":"pattern","title":"JWT refresh tokens must rotate on every use","summary":"...","confidence":"high","tags":["auth","jwt","security"],"evidence_refs":["..."],"routed_to":"spec","routed_id":"coding-conventions.md#INS-a1b2c3d4","source":"retrospective","captured_at":"2026-04-11T10:00:00Z"}
-```
+### JWT refresh tokens must rotate on every use
 
-### learning-index.json
+Refresh-on-use prevents replay attacks. Implemented in src/auth/refresh.ts; should become a project-wide convention.
 
-```json
-{
-  "entries": [
-    {
-      "id": "INS-a1b2c3d4",
-      "type": "insight",
-      "timestamp": "2026-04-11T10:00:00Z",
-      "file": "lessons.jsonl",
-      "summary": "JWT refresh tokens must rotate on every use",
-      "tags": ["auth", "jwt", "security"],
-      "lens": "technical",
-      "category": "pattern",
-      "phase": 1,
-      "phase_slug": "01-auth",
-      "confidence": "high",
-      "routed_to": "spec",
-      "routed_id": "coding-conventions.md#INS-a1b2c3d4"
-    }
-  ],
-  "_metadata": {
-    "created": "2026-04-11T10:00:00Z",
-    "version": "1.0"
-  }
-}
+- **Phase**: 1 (01-auth)
+- **Lens**: technical
+- **Confidence**: high
+- **Evidence**: .workflow/scratch/plan-auth-2026-04-15/verification.json#gaps[2]
+- **Routed to**: spec (coding-conventions.md#INS-a1b2c3d4)
+
+</spec-entry>
 ```
 

package/workflows/specs-load.md

@@ -5,12 +5,12 @@ Load spec files filtered by category. Supports project, global, team, and person
 ## Arguments
 
 ```
-$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--category <type>] [keyword]"
+$ARGUMENTS: "[--scope <scope>] [--uid <uid>] [--category <category>] [keyword]"
 
 --scope     -- load scope: project (default) | global | team | personal
 --uid       -- user id for personal scope (auto-detected from git if omitted)
---category  -- filter by category (1:1 mapping to file):
-               coding | arch | quality | debug | test | review | learning | all
+--category  -- filter by category: coding | arch | test | review | debug | quality | learning
+               Loads category's primary doc in full + cross-file entries with matching category attr
 keyword     -- optional, grep within loaded specs for matching sections
 ```
 
@@ -18,16 +18,17 @@ keyword     -- optional, grep within loaded specs for matching sections
 
 Each category loads exactly one file per layer. Same mapping as spec-add.
 
-| Category | File loaded |
-|----------|------------|
-| `coding` | `coding-conventions.md` |
-| `arch` | `architecture-constraints.md` |
-| `quality` | `quality-rules.md` |
-| `debug` | `debug-notes.md` |
-| `test` | `test-conventions.md` |
-| `review` | `review-standards.md` |
-| `learning` | `learnings.md` |
-| `all` (default) | All `.md` files in specs/ |
+## File → Primary Category Mapping
+
+| File | Category |
+|------|----------|
+| `coding-conventions.md` | coding |
+| `architecture-constraints.md` | arch |
+| `test-conventions.md` | test |
+| `review-standards.md` | review |
+| `debug-notes.md` | debug |
+| `quality-rules.md` | quality |
+| `learnings.md` | learning |
 
 ## Layer Order by Scope
 
@@ -44,7 +45,7 @@ Each layer is prefixed with a section header when multi-layer.
 
 ### Step 1: Parse Arguments
 
-Extract `--scope`, `--uid`, `--category <type>` and remaining text (keyword for grep).
+Extract `--scope`, `--uid`, `--category <category>` and remaining text (keyword for grep).
 
 ### Step 2: Load Specs via CLI
 

package/workflows/tools-spec.md

@@ -0,0 +1,65 @@
+# Tool Spec Reference
+
+Shared reference for tool spec registration and execution commands.
+
+## Storage
+
+Tool specs are stored as knowhow documents in `.workflow/knowhow/` with `tool: true` in YAML frontmatter. Tool registration creates knowhow files, not spec entries. The `category` field determines which `spec load --category` queries match this tool.
+
+## Entry Format
+
+Knowhow document (`knowhow/RCP-<slug>.md`):
+```yaml
+---
+title: Tool Name
+type: recipe
+tool: true
+summary: "Use when {timing}. {scope description}"
+tags: [keyword1, keyword2]
+category: coding
+---
+
+## Prerequisites
+...
+
+## Steps
+1. ...
+```
+
+## Description Rules
+
+- First line after `### Title` must state **when to use** this tool
+- For ref entries: `spec load` shows only the first 200 chars after heading — timing must be in that window
+- For ref knowhow docs: YAML `summary` field is shown by `wiki list` and wiki-role-loader hook
+
+## Discovery Path
+
+```
+Register → tools.md → spec load --category <category> / spec-injector auto-inject → agent discovers tool
+```
+
+Agents discover tool specs via:
+- `spec load --category <category>` — returns entries matching the category
+- `spec-injector` hook — auto-injects at Agent launch based on agent type
+- `spec load --keyword <word>` — keyword search across all entries
+
+## Category Reference
+
+| Category | Agent types | Tool examples |
+|----------|-------------|---------------|
+| coding | code-developer, workflow-executor | Build, deploy, integrate |
+| test | tdd-developer, test-fix-agent | Test flows, verification steps |
+| review | workflow-reviewer | Checklists, audit standards |
+| arch | workflow-planner | Design flows, analysis steps |
+| debug | debug-explore-agent | Diagnostic flows, investigation |
+
+## CLI Commands
+
+```bash
+# Register tool as knowhow document
+maestro knowhow add "knowhow/RCP-<slug>.md" --type recipe --tool
+
+# Load specs by category
+maestro spec load --category <category>
+maestro spec load --category <category> --keyword <word>
+```