maestro-flow 0.4.19 → 0.4.21

package/workflows/codebase-rebuild.md

@@ -181,9 +181,143 @@ b. Update project.md Tech Stack (if exists):
 
 ```
 Display summary: component/feature/requirement/ADR/file counts.
+If KG pipeline ran: include KG node/edge/layer/tour counts.
 If mapper agents failed: log W001.
 If not --skip-commit: suggest committing generated docs.
-Suggest next: manage-status (review) or manage-codebase-refresh (incremental updates).
+Suggest next:
+  - manage-status (review)
+  - manage-codebase-refresh (incremental updates)
+  - maestro kg stats (verify KG)
+  - maestro wiki list --keyword kg (verify wiki integration)
+  - maestro kg diff-wiki (future change impact analysis)
+```
+
+---
+
+## Knowledge Graph Pipeline (Steps 10–17)
+
+> **Optional.** Only runs when UA vendor is installed at
+> `~/.maestro/vendor/ua/understand-anything-plugin/packages/core/dist/index.js`.
+> If not found, skip Steps 10–17 with warning:
+> *"KG pipeline skipped: run `scripts/ua-vendor-setup.sh` first"*
+
+All intermediate artifacts are written to `.workflow/codebase/.kg-tmp/`.
+
+### Step 10: KG Pipeline — Project Scan
+
+```
+node ~/.maestro/vendor/ua/understand-anything-plugin/skills/understand/scan-project.mjs \
+  "$PROJECT_ROOT" \
+  "$PROJECT_ROOT/.workflow/codebase/.kg-tmp/scan-result.json"
+```
+
+Output: `.workflow/codebase/.kg-tmp/scan-result.json`
+
+### Step 11: KG Pipeline — Compute Batches
+
+```
+node ~/.maestro/vendor/ua/understand-anything-plugin/skills/understand/compute-batches.mjs \
+  "$PROJECT_ROOT"
+```
+
+Output: `.workflow/codebase/.kg-tmp/batches.json`
+
+### Step 12: KG Pipeline — File Analysis (Parallel Delegates)
+
+```
+For each batch in batches.json, dispatch a delegate:
+
+  maestro delegate "<prompt from kg-file-analyze template>" \
+    --rule kg-file-analyze --mode analysis --cd "$PROJECT_ROOT"
+
+Run up to 5 delegates concurrently (run_in_background: true).
+Each produces batch-N.json in .kg-tmp/
+```
+
+### Step 13: KG Pipeline — Merge Batch Graphs
+
+```
+node scripts/merge-batch-graphs.mjs "$PROJECT_ROOT" \
+  --intermediate-dir "$PROJECT_ROOT/.workflow/codebase/.kg-tmp"
+```
+
+Output: `.workflow/codebase/.kg-tmp/assembled-graph.json`
+
+### Step 14: KG Pipeline — Architecture Analysis
+
+```
+maestro delegate "<prompt>" --rule kg-architecture --mode analysis
+```
+
+This **replaces** the original Architecture mapper (Mapper 2).
+Mapper 2 no longer runs independently — its output is produced here instead.
+
+Output: `.workflow/codebase/.kg-tmp/layers.json`
+
+### Step 15: KG Pipeline — Tour Generation
+
+```
+maestro delegate "<prompt>" --rule kg-tour-build --mode analysis
+```
+
+Output: `.workflow/codebase/.kg-tmp/tour.json`
+
+### Step 16: KG Pipeline — Validation
+
+```
+Run inline validation (Node.js script from UA, adapted):
+  - Check all nodes have required fields (id, type, name, filePath)
+  - Check referential integrity (all edge source/target refs exist as node ids)
+  - Check layer coverage (every file-type node appears in exactly 1 layer)
+  - Check tour structure (all tour step refs resolve to valid nodes)
+
+If validation fails: log errors but still write the graph (with "valid": false flag).
+```
+
+### Step 17: KG Pipeline — Save Knowledge Graph
+
+```
+Assemble final KnowledgeGraph JSON:
+
+{
+  "version": "1.0.0",
+  "valid": true|false,
+  "project": {
+    "name": "<from state.json or package.json>",
+    "languages": [<detected>],
+    "frameworks": [<detected>],
+    "description": "<from project.md>",
+    "analyzedAt": "<ISO timestamp>",
+    "gitCommitHash": "<current HEAD>"
+  },
+  "nodes": [<from assembled-graph.json>],
+  "edges": [<from assembled-graph.json>],
+  "layers": [<from Step 14 layers.json>],
+  "tour": [<from Step 15 tour.json>]
+}
+
+Write to: .workflow/codebase/knowledge-graph.json
+Clean up: remove .workflow/codebase/.kg-tmp/ directory
+```
+
+### Step 18: KG → Wiki Index Integration
+
+```
+When knowledge-graph.json is successfully written:
+  The WikiIndexer will automatically index KG nodes as virtual wiki entries
+  on next wiki access (via adaptUaKgGraph virtual adapter).
+
+  Generated virtual entries:
+    - uakg-{node-id} for each GraphNode (type: knowhow, virtualKind: ua-kg-node)
+    - uakg-layer-{id} for each Layer (virtualKind: ua-kg-layer)
+    - uakg-tour-{order} for each TourStep (virtualKind: ua-kg-tour-step)
+
+  Cross-referencing:
+    - KG nodes are linked to existing codebase-comp-* entries via filePath matching
+    - Edge semantics preserved in ext.kgEdges for downstream semantic traversal
+
+  No manual action required — indexing is lazy and triggered on first wiki access.
+  To verify: run `maestro wiki list --keyword kg` after rebuild.
 ```
 
 ---
@@ -196,6 +330,10 @@ Suggest next: manage-status (review) or manage-codebase-refresh (incremental upd
 | .workflow/ missing | Fail: "Run /workflow:init first" |
 | File read errors | Log warning, skip file, continue scan |
 | Existing codebase/ without --force | Prompt user for confirmation |
+| UA vendor not installed | Skip Steps 10–18 with warning, continue normally |
+| KG batch delegate failed | Log warning, continue with remaining batches |
+| KG validation failed | Write knowledge-graph.json with `"valid": false`, log errors |
+| Wiki index rebuild failed | Non-fatal — KG data still written, wiki indexing retries on next access |
 
 ## Output Files
 
@@ -206,5 +344,7 @@ Suggest next: manage-status (review) or manage-codebase-refresh (incremental upd
 | `.workflow/codebase/tech-registry/{slug}.md` | Per-component documentation |
 | `.workflow/codebase/feature-maps/_index.md` | Feature index |
 | `.workflow/codebase/feature-maps/{slug}.md` | Per-feature documentation |
+| `.workflow/codebase/knowledge-graph.json` | Knowledge Graph with nodes, edges, layers, and tour (if UA vendor installed) |
+| `.workflow/wiki-index.json` | Updated on next wiki access: KG nodes indexed as virtual entries (automatic) |
 | `.workflow/state.json` | Updated: last_codebase_rebuild timestamp |
 | `.workflow/project.md` | Updated: Tech Stack section refreshed |

package/workflows/codebase-refresh.md

@@ -57,6 +57,26 @@ specs_content = maestro spec load --category arch
 
 Used in Step 4-5 to validate refreshed docs against architectural expectations.
 
+### Step 3.6: KG Impact Analysis (if KG exists)
+
+```
+If .workflow/codebase/knowledge-graph.json exists:
+  Run: maestro kg diff-wiki --json
+  Parse output for affectedWiki entries.
+
+  If affectedWiki is non-empty:
+    Log WARNING for each affected wiki entry:
+      "KG impact: code changes affect [entry.id] — [entry.title] (via [reason])"
+
+    Add affected entry IDs to the refresh queue for human review.
+
+  Log summary: "KG analysis: {directNodes} direct, {impactedNodes} impacted KG nodes,
+    {affectedWiki.length} wiki entries flagged"
+
+If .workflow/codebase/knowledge-graph.json does not exist:
+  Skip silently (KG not generated).
+```
+
 ---
 
 ### Step 4: Re-scan Affected Components

package/workflows/finish-work.md

@@ -4,7 +4,7 @@ Last step of session commands. Inline-extracts spec/knowhow from this single ses
 
 ## Inputs
 
-Caller passes: `SESSION_DIR`, `SESSION_TYPE` (brainstorm | analyze | blueprint | plan | execute | verify), `SESSION_ID`, `LINKED_MILESTONE` (optional).
+Caller passes: `SESSION_DIR`, `SESSION_TYPE` (grill | brainstorm | analyze | blueprint | plan | execute | verify), `SESSION_ID`, `LINKED_MILESTONE` (optional).
 
 ## Steps
 
@@ -14,7 +14,9 @@ Scan `SESSION_DIR` for any of these files (any absent → skip silently):
 
 | File | Source | Used for |
 |------|--------|----------|
-| `context-package.json` | brainstorm/analyze/blueprint | constraints + insights |
+| `context-package.json` | grill/brainstorm/analyze/blueprint | constraints + insights |
+| `terminology.md` | grill | domain terms with code references |
+| `grill-report.md` | grill | stress-test decisions + risk register |
 | `conclusions.json` | analyze | decisions |
 | `reflection-log.md` | execute | lessons + pitfalls |
 | `{role}/analysis.md` | brainstorm | role decisions |
@@ -33,6 +35,9 @@ Iterate detected files; build a `fragments[]` array. Each fragment: `{ kind, cat
 | `conclusions.json#recommendations[]` (priority ≥ medium) | knowhow | knowhow (`REF`) | derived from area |
 | `reflection-log.md` "## Lessons" / "## Pitfalls" sections | learning | spec (category `learning`) or knowhow (`KNW`) by length: < 200 chars → spec, else knowhow | `learning` |
 | `{role}/analysis.md` §2 Decisions[status=locked] | rule | spec | role-derived (`arch` for system-architect, `coding` for code-quality, etc.) |
+| `grill-report.md` "## Synthesis" locked decisions | rule | spec | `arch` if scope/integration/security branch, else `coding` |
+| `grill-report.md` "## Risk Register" items (severity ≥ medium) | knowhow | knowhow (`REF`) | `debug` |
+| `terminology.md` locked terms | knowhow | knowhow (`REF`) | `coding` |
 
 **Confidence scoring** (drop if < 0.5):
 - +0.3 if `status == "locked"` or section is explicit "## Decisions"