maestro-flow 0.4.23 → 0.4.25

package/workflows/analyze.md

@@ -286,7 +286,7 @@ Append initial Intent Coverage Check to discussion.md.
 
 **Step 4.6: Baseline Confidence Scoring**
 
-Dimensions = the 6 analysis dimensions. Factors (weights): findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Score each factor per dimension from Round 1 results. Append baseline confidence table to discussion.md. Thresholds: <60% 继续深入 | 60-80% 可选 | 80-95% 接近收敛 | >95% 建议收敛.
+Dimensions = the 6 analysis dimensions. Factors (weights): findings_depth(.30), evidence_strength(.25), coverage_breadth(.20), user_validation(.15), consistency(.10). Score each factor per dimension from Round 1 results. Append baseline confidence table to discussion.md. Thresholds: <60% 继续深入 | 60-80% 需用户确认收敛 | >80% 建议收敛.
 
 ### Step 5: Interactive Discussion Loop
 
@@ -297,21 +297,27 @@ Generate 1-2 sentence recap linking previous round conclusions to current starti
 
 **5.2: Present Findings** from latest exploration/analysis
 
-**5.3: Gather Feedback** (AskUserQuestion, single-select, header: "分析反馈"):
-- **继续深入**: Deepen analysis — auto or user-specified direction
-- **调整方向**: Different focus or specific questions
-- **补充信息**: User has additional context, constraints, or corrections
-- **分析完成**: Sufficient — exit to Phase 4
+**5.3: Gather Feedback**
+
+AskUserQuestion (single-select, header: "分析反馈"):
+- **继续深入** (Recommended) — deepen lowest-confidence dimension
+- **调整方向** — different focus or specific questions
+- **补充信息** — user has additional context, constraints, or corrections
+- **分析完成** — sufficient, exit to scoring
+
+Question text: `Round {N} | Confidence: {overall}% | 最弱: {weakest_dim} ({dim_score}%)`
 
 **5.4: Process Response** (always record user choice + impact to discussion.md):
 
 | Choice | Action |
 |--------|--------|
-| 继续深入 | Sub-question (max 4 options: 3 context-driven + 1 heuristic frame-breaker) → CLI/agent exploration → merge findings |
+| 继续深入 | AskUserQuestion sub-direction (below) → CLI/agent exploration → merge findings |
 | 调整方向 | Capture new direction → new CLI exploration → Record Decision (old vs new, reason, impact) |
 | 补充信息 | Capture user input → integrate → answer questions via CLI if needed → Record corrections |
 | 分析完成 | Exit loop → Record why concluding |
 
+**继续深入 sub-direction**: AskUserQuestion (single-select, header: "深入方向", max 4 options: 3 context-driven from unresolved questions/low-confidence findings/unexplored dimensions + 1 heuristic "换角度审视"). "Other" auto-provided for custom direction.
+
 **5.5: Update discussion.md** after each round:
 - **Append** Round N: user input, direction, Q&A, corrections, new insights
 - **Append Technical Solutions** — for every solution proposed, validated, or rejected this round, record immediately using Technical Solution Record Format in `#### Technical Solutions`
@@ -347,7 +353,7 @@ Re-evaluate factors per dimension. Show delta: `Confidence: {prev}% → {current
 - **Stall Detection**: delta < 5% for 2 consecutive rounds → "分析可能停滞，建议切换方向或收敛"
 
 **5.10: Pre-Synthesis Readiness Gate** (on "分析完成"):
-Block if: ❌ items without deferral | any dimension < 40% | no pressure pass | unresolved contradictions. If blocked → AskUserQuestion: 补充后继续 or 忽略风险并继续 (record `residual_risks[]`).
+Block if: ❌ items without deferral | any dimension < 40% | no pressure pass | unresolved contradictions | overall confidence < 80%. If blocked → AskUserQuestion: 补充后继续 or 忽略风险并继续 (record `residual_risks[]`, note accepted confidence level).
 
 **Auto mode (-y)**: auto-deepen ≤3 rounds, readiness gate auto-overrides with residual risk recording.
 
@@ -603,11 +609,11 @@ Display summary:
 - Key conclusions (if full mode)
 - Session stats
 
-**Next Step Selection** (AskUserQuestion, single-select, header: "Next Step"):
-- **快速执行**: Skill({ skill: "maestro-quick", args: "{task_description} --full" }) — build context from conclusions
-- **进入规划**: Phase mode → Skill({ skill: "maestro-plan", args: "{phase}" }); Scratch mode → Skill({ skill: "maestro-plan", args: "--dir {output_dir}" }) — plan directly against scratch directory
-- **产出Issue**: Convert recommendations to tracked issues
-- **完成**: No further action
+AskUserQuestion (single-select, header: "Next Step"):
+- **快速执行** — build context from conclusions, invoke maestro-quick
+- **进入规划** — phase planning (maestro-plan)
+- **产出Issue** — convert recommendations to tracked issues
+- **完成** — no further action
 
 Handle selection:
 

package/workflows/codebase-rebuild.md

@@ -194,123 +194,36 @@ Suggest next:
 
 ---
 
-## Knowledge Graph Pipeline (Steps 10–17)
+## Knowledge Graph Pipeline (Step 10)
 
-> **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"*
+Uses the native `maestro kg index` command (`src/graph/analyzers/fs-analyzer.ts`) to scan the codebase and generate the knowledge graph. No external dependencies required.
 
-All intermediate artifacts are written to `.workflow/codebase/.kg-tmp/`.
+### Step 10: Generate Knowledge Graph
 
-### 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
-
+maestro kg index --src "$PROJECT_ROOT/src"
 ```
-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>]
-}
+This single command performs:
+  - File system scan and code entity extraction (nodes, edges)
+  - Import/call graph analysis and test pairing (tested_by edges)
+  - Layer classification and topological tour generation
+  - Validation (referential integrity, layer coverage, tour structure)
+  - Write to `.workflow/codebase/knowledge-graph.json`
 
-Write to: .workflow/codebase/knowledge-graph.json
-Clean up: remove .workflow/codebase/.kg-tmp/ directory
-```
+If validation fails: the graph is still written with `"valid": false` flag.
 
-### Step 18: KG → Wiki Index Integration
+### Step 11: 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).
+  The WikiIndexer automatically indexes KG nodes as virtual wiki entries
+  on next wiki access (via adaptKnowledgeGraph 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)
+    - kg-{node-id} for each GraphNode (type: knowhow, virtualKind: kg-node)
+    - kg-layer-{id} for each Layer (virtualKind: kg-layer)
+    - kg-tour-{order} for each TourStep (virtualKind: kg-tour-step)
 
   Cross-referencing:
     - KG nodes are linked to existing codebase-comp-* entries via filePath matching
@@ -330,8 +243,6 @@ When knowledge-graph.json is successfully written:
 | .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 |
 
@@ -344,7 +255,7 @@ When knowledge-graph.json is successfully written:
 | `.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/codebase/knowledge-graph.json` | Knowledge Graph with nodes, edges, layers, and tour |
 | `.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/execute.md

@@ -295,16 +295,17 @@ For each wave in execution_queue (sequential):
     IF executor == "agent":
       Spawn workflow-executor agent (fresh 200k context) with:
         task definition, phase context, prior wave summaries, specs_content, context.md, analysis.md
-      Agent: implement task → verify convergence → auto-fix (max 3) → checkpoint if blocked
-      On success: atomic commit (if auto-commit), write .summaries/${task_id}-summary.md
-      Update .task/${task_id}.json: status = "completed" | "blocked"
+      Agent internally handles full lifecycle:
+        implement → verify convergence → auto-fix (max 3) → commit → write .summaries/${task_id}-summary.md → update .task/${task_id}.json status
+        (checkpoint if blocked)
+      Main flow: verify agent wrote summary + updated status, collect result
 
     ELSE (CLI path via maestro delegate):
       fixedId = "${PHASE_NUM || 'scratch'}-${PHASE_SLUG}-${task_id}"
       Store fixedId in index.json.execution.delegate_ids[task_id]
       Dispatch: maestro delegate "${prompt}" --to ${executor} --mode write --id ${fixedId}
-      Post-dispatch: verify convergence criteria against file state
-      Write summary, update task status, auto-commit if enabled
+      Main flow post-dispatch: verify convergence criteria against file state
+      Main flow writes: .summaries/${task_id}-summary.md, update .task/${task_id}.json status, auto-commit if enabled
 
     Collect result: { task_id, status, executor, summary_path, commit_hash, delegate_id }
     Clear state.json.current_task_id