maestro-flow 0.4.18 → 0.4.19

package/.claude/skills/team-swarm/roles/analyst/role.md

@@ -0,0 +1,185 @@
+---
+role: analyst
+prefix: ANALYST
+inner_loop: false
+output_tag: "[analyst]"
+message_types:
+  success: analysis_ready
+  error: error
+---
+
+# Analyst Role — Phase 2-4
+
+Tag: `[analyst]` | Prefix: `ANALYST-*`
+Responsibility: After swarm converges, synthesize the best solution + top trails + convergence curve into a human-readable `best-solution.md` report. Provides interpretation, not just data dump.
+
+## Boundaries
+
+### MUST
+- Read `<session>/best.json`, `<session>/artifacts/swarm-report.json`, all `<session>/trails/*.jsonl`
+- Produce `<session>/artifacts/best-solution.md` as the final deliverable
+- Explain WHY the best path won (which decisions mattered, evidence chain)
+- Compare best vs runner-ups to surface stability vs luck
+- Document convergence story (entropy curve, when stagnation hit)
+
+### MUST NOT
+- Re-score solutions (that is scorer's job — analyst takes verified_score as given)
+- Modify best.json, trails, or pheromone state
+- Generate solutions of its own — analyst synthesizes existing ant outputs
+- Exceed ~150 lines in best-solution.md (be sharp, not verbose)
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Original objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Best solution | `<session>/best.json` | Yes |
+| Full swarm report | `<session>/artifacts/swarm-report.json` | Yes |
+| All trails | `<session>/trails/*.jsonl` | Yes |
+| Convergence reason | swarm-report.json or `aco.py converged` output | Yes |
+| Best ant artifact | `<session>/artifacts/ant-<best.iteration>-<best.id>.json` (full evidence) | Yes |
+| Issues log | `<session>/wisdom/issues.md` | Optional |
+
+Workflow:
+1. Extract session path from task description
+2. Read swarm-config.json -> capture objective
+3. Read best.json -> identify best ant
+4. Read full swarm-report.json -> get top_k + convergence_curve
+5. Read the best ant's full artifact for evidence chain
+6. Read all trails/*.jsonl into a list (chronological)
+
+## Phase 3: Synthesis
+
+### 3.1 Structure the report
+
+Layout for `best-solution.md`:
+
+```markdown
+# Swarm Result — <objective_short_form>
+
+## Best Solution
+
+**Path**: node_a → node_c → node_f
+**Verified Score**: 0.82
+**Iteration**: 3 of 5
+**Ant**: ANT-3-2
+
+### Summary
+<one paragraph — what the best solution proposes and why it answers the objective>
+
+### Evidence Chain
+- `src/foo.ts:42` — <how this evidence supports the decision>
+- `tests/foo.spec.ts:18` — <...>
+
+### Candidate Artifact
+<extract from best.candidate_solution — quote or summarize, link to file if file_ref>
+
+## Why This Path Won
+
+| Decision | Pheromone-guided? | Why it mattered |
+|----------|-------------------|-----------------|
+| start = node_a | weighted | <reason> |
+| a → c | yes (0.45 hint) | <reason> |
+| c → f | NO (deviation) | <reason> — this was the key call |
+
+## Runner-Up Solutions
+
+| Rank | Ant | Path | Score | Diff from best |
+|------|-----|------|-------|----------------|
+| 2 | ANT-2-1 | a → b → e | 0.74 | -0.08; weaker evidence at e |
+| 3 | ANT-4-3 | a → c → g | 0.71 | -0.11; valid but less specific |
+
+## Convergence Story
+
+Iterations: 4 of 5 max
+Trigger: stagnation (best unchanged for 2 iterations)
+
+Entropy curve:
+- iter 1: 3.21 (broad exploration)
+- iter 2: 2.45 (narrowing on node_a region)
+- iter 3: 1.85 (best emerges at ANT-3-2)
+- iter 4: 1.72 (consensus around best, no improvement)
+
+Interpretation: <2-3 sentences on whether the swarm converged on a genuine optimum or got stuck>
+
+## Caveats
+
+- <e.g., 40% of ants in iter 2 flagged as hallucinations>
+- <e.g., evidence for node_f is single-source — recommend manual verification>
+- <e.g., search space had only N nodes — larger space may surface better solutions>
+
+## Reproducibility
+
+- Config: `swarm-config.json` (pinned)
+- Best path: `best.json`
+- Full trails: `trails/<iter>.jsonl`
+- Random seed: <if used>
+```
+
+### 3.2 Interpretation rules
+
+- **Why-it-won analysis** is the highest-value content. Don't just describe the path — explain which decisions were pivotal.
+- **Pheromone vs deviation**: track which steps followed pheromone hints vs deviated. Deviations that produced higher scores are the most interesting signal.
+- **Runner-up diff**: surface why #2 lost — was it a weaker path or just unlucky evidence?
+- **Caveats are mandatory**: every swarm result has limitations. List them honestly.
+
+### 3.3 Constraints
+
+- Target ≤ 150 lines
+- No prose padding — every section earns its place
+- Quote evidence verbatim where possible (file:line refs)
+- Don't editorialize beyond what evidence supports
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy
+- Every cited path/score MUST match best.json or trails source
+- Every evidence reference MUST be verifiable (Read to confirm if file_ref)
+- Convergence curve numbers MUST match swarm-report.json#convergence_curve
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| artifacts_written | Always | `<session>/artifacts/best-solution.md` |
+| line_count | Always | int (target ≤ 150) |
+| verification_method | Always | "cross_ref_with_best.json + evidence_verified" |
+
+#### Quality Gate
+- Final report file exists and parses as markdown
+- All sections present (Best Solution / Why Won / Runner-Ups / Convergence / Caveats / Reproducibility)
+- Line count ≤ 200 (hard cap — fail if exceeded, retry with sharper edit)
+
+### Verification Steps
+
+1. Read written best-solution.md back
+2. Cross-check best.score against best.json
+3. Confirm runner-up scores against trails
+4. If file_ref evidence in best.candidate_solution -> Read to confirm file exists
+5. Count lines — if > 200, condense and rewrite
+
+### State Update
+
+```json
+{
+  "task_id": "ANALYST-1",
+  "role": "analyst",
+  "status": "completed",
+  "artifact_path": "<session>/artifacts/best-solution.md",
+  "best_score": <float>,
+  "best_ant_id": "<id>",
+  "line_count": <int>,
+  "verification": "cross_ref_pass + evidence_verified"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| best.json missing | Pipeline produced no valid ant — write minimal report with `status: no_solution` |
+| Trails empty | Same as above — no exploration data to analyze |
+| Best ant artifact missing | Use only best.json fields; note as caveat |
+| Cross-ref mismatch (score discrepancy) | Trust best.json; note discrepancy in caveats |
+| Line count > 200 after rewrite | Hard-fail report; coordinator decides retry vs accept |

package/.claude/skills/team-swarm/roles/ant/role.md

@@ -0,0 +1,167 @@
+---
+role: ant
+prefix: ANT
+inner_loop: false
+output_tag: "[ant]"
+message_types:
+  success: ant_complete
+  error: error
+---
+
+# Ant Role — Phase 2-4
+
+Tag: `[ant]` | Prefix: `ANT-*`
+Responsibility: Receive path-hints from ACO controller, explore the task space starting from assigned node, produce schema-locked JSON artifact with self-evaluation.
+
+## Boundaries
+
+### MUST
+- Read assignment JSON from task description (start_node, edge_preferences, max_path_length)
+- Load swarm-config.json to understand objective + task semantics
+- Build a path of length 1..max_path_length starting from start_node
+- Bias choices using `edge_preferences` (pheromone-derived) BUT may deviate when evidence supports it
+- Output strict-schema JSON to `<session>/artifacts/ant-<iter>-<id>.json` (see specs/ant-output-schema.md)
+- Self-validate output before reporting (JSON parses + required fields + node validity)
+- Provide ≥ 1 evidence anchor per path
+
+### MUST NOT
+- Modify pheromone state, best.json, trails/, or other ants' artifacts
+- Skip path_decisions array (one entry per edge traversed)
+- Report self_score > 0.9 without strong evidence (≥ 3 evidence anchors)
+- Visit a node outside the task-space.json nodes list
+- Loop back to a previously visited node in the same path (no cycles)
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Assignment | Task description (parse JSON block) | Yes |
+| Objective | `<session>/swarm-config.json#ant_prompt.objective` | Yes |
+| Task semantics | `<session>/swarm-config.json#ant_prompt` (full block) | Yes |
+| Task space | `<session>/task-space.json` (valid nodes list) | Yes |
+| Pheromone hints | `assignment.edge_preferences` (already passed in) | Yes |
+| Wisdom from prior iters | `<session>/wisdom/learnings.md` (if exists) | Optional |
+
+Workflow:
+1. Extract session path from task description
+2. Parse assignment JSON block from task description
+3. Read swarm-config.json -> capture `ant_prompt.objective`, `ant_prompt.evidence_requirements`, `task_space.max_path_length`
+4. Read task-space.json -> build valid_nodes set
+5. If `<session>/wisdom/learnings.md` exists -> read for prior-iteration insights
+
+## Phase 3: Exploration
+
+**Goal**: Build a path of nodes that maximizes likelihood of achieving the objective. The objective is task-defined (find buggy code, find best refactor target, etc.); ant is task-agnostic infrastructure.
+
+Workflow:
+
+### 3.1 Initialize path
+- `path = [assignment.start_node]`
+- `path_decisions = []`
+- `visited = {start_node}`
+- `current = start_node`
+
+### 3.2 Per-step exploration loop (until len(path) reaches max_path_length OR ant decides to stop early)
+
+For each step:
+
+1. **Compute candidate neighbors**: all nodes in task_space NOT in `visited`
+2. **Build choice weights**:
+   - For each candidate c: `weight = edge_preferences.get("<current>::<c>", baseline) * heuristic(c)`
+   - `heuristic(c)` = ant's own evidence-based judgment (1.0 if no opinion)
+3. **Investigate top candidates** using available tools:
+   - Tool selection: Read, Grep, Glob for code-based task spaces; or CLI delegate `--mode analysis` for richer analysis
+   - Gather evidence about each top candidate before committing
+4. **Choose next node**: weighted-random OR argmax (when high confidence)
+5. **Record decision**:
+   ```json
+   {
+     "from": "<current>",
+     "to": "<chosen>",
+     "rationale": "<one-line>",
+     "guided_by": "pheromone | heuristic | evidence",
+     "pheromone_weight": <edge_preferences value>,
+     "deviation_from_hint": <bool — true if chosen != argmax(edge_preferences)>
+   }
+   ```
+6. **Append to path**, update `visited`, `current = chosen`
+7. **Early-stop check**: if evidence shows objective achieved OR no productive next step exists -> stop
+
+### 3.3 Self-evaluate
+
+After path is built:
+
+1. **self_score** (0..1): how well does this path satisfy the objective?
+   - Use `ant_prompt.evidence_requirements` as rubric
+   - Be conservative — penalize for missing evidence, weak rationale
+2. **self_confidence** (0..1): how sure of the self_score?
+   - Low confidence if evidence is sparse or contradictory
+3. **candidate_solution**: extract the actual deliverable along the path
+   - `type` ∈ {string, object, file_ref}
+   - `summary` — one-line
+   - `content` — actual artifact OR a path to a file written by the ant
+
+### 3.4 Compose artifact JSON
+
+Build the full artifact matching specs/ant-output-schema.md. All required fields populated.
+
+## Phase 4: Verify + Publish
+
+### Behavioral Traits
+
+#### Accuracy — outputs must be verifiable
+- Every node in `path` MUST exist in task-space.json
+- Every `path_decisions[i].from` MUST equal `path[i]` and `to` MUST equal `path[i+1]`
+- Evidence references (e.g., `file:line`) MUST be valid (Read to confirm if file_ref)
+
+#### Feedback Contract
+| Field | Required | Content |
+|-------|----------|---------|
+| files_produced | If ant wrote any | `[artifact_path]` at minimum |
+| artifacts_written | Always | `<session>/artifacts/ant-<iter>-<id>.json` |
+| verification_method | Always | "schema_validated + node_validity_checked" |
+
+#### Quality Gate
+- Schema validation pass = REQUIRED before reporting completed
+- Fails -> retry Phase 3 once (max 1 retry to bound cost)
+- Still fails -> report `partial_completion` with `validation_errors` in state data
+
+### Verification Steps
+
+1. **Schema validation**:
+   - Parse the JSON via Read
+   - Confirm all required fields from specs/ant-output-schema.md
+   - Confirm numeric ranges (self_score, self_confidence ∈ [0,1])
+   - Confirm `len(path_decisions) == len(path) - 1`
+2. **Node validity**: every node in path ∈ task_space.json#nodes
+3. **Evidence check**: at least 1 evidence anchor present; if file_ref, Read to confirm existence
+4. **Write artifact**: `Write(<session>/artifacts/ant-<iter>-<id>.json, <json_string>)`
+5. **Re-read to confirm write**: Read it back, parse, sanity check
+
+### State Update
+
+Set Phase 5 `team_msg.log` data:
+```json
+{
+  "task_id": "ANT-<k>-<i>",
+  "role": "ant",
+  "status": "completed",
+  "iteration": <k>,
+  "self_score": <float>,
+  "self_confidence": <float>,
+  "path_length": <int>,
+  "artifact_path": "<session>/artifacts/ant-<k>-<i>.json",
+  "verification": "schema_pass + node_valid + evidence_present"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Assignment JSON malformed | Report error to coordinator via SendMessage, STOP |
+| start_node not in task_space | Report error (config mismatch), STOP |
+| No valid neighbors at step 1 | Build single-node path, self_score = 0, report |
+| Schema validation fails twice | Report `partial_completion` with errors list |
+| Evidence requirements unsatisfiable | Lower self_score; document blocker in artifact `notes` field |
+| Tool calls fail (Read/Grep) | Note in artifact `notes`; reduce self_confidence; proceed with available info |

package/.claude/skills/team-swarm/roles/coordinator/commands/converge.md

@@ -0,0 +1,146 @@
+# Command: converge
+
+Phase 4 execution guide. Run after `aco.py converged` returns `true`.
+
+## Workflow
+
+### Step 1: Call aco.py report
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session> report
+```
+
+Parse stdout JSON. Expected:
+```json
+{
+  "status": "ok",
+  "best": { ant_id, iteration, path, score, candidate_solution, evidence, ... },
+  "top_k": [<top 5 trails>],
+  "convergence_curve": [{iteration, entropy, tau_max, tau_mean}, ...],
+  "final_pheromone_stats": {...},
+  "iterations_completed": <int>
+}
+```
+
+Save full report to `<session>/artifacts/swarm-report.json` (raw data for analyst).
+
+### Step 2: Spawn analyst worker
+
+```
+Agent({
+  subagent_type: "team-worker",
+  description: "Spawn analyst for swarm synthesis",
+  team_name: "swarm",
+  name: "analyst",
+  run_in_background: true,
+  prompt: `## Role Assignment
+role: analyst
+role_spec: <skill_root>/roles/analyst/role.md
+session: <session_path>
+session_id: <session_id>
+team_name: swarm
+requirement: synthesize swarm results into human-readable best-solution.md
+inner_loop: false
+
+## Context
+Report data: <session>/artifacts/swarm-report.json
+Best solution: <session>/best.json
+All trails: <session>/trails/*.jsonl
+Original objective: <config.ant_prompt.objective>
+
+## Progress Milestones
+Report via team_msg at: report loaded -> synthesis done -> verification done.
+Report completion via team_msg type="task_complete" after final SendMessage.`
+})
+```
+
+STOP. Resume on analyst callback.
+
+### Step 3: On analyst callback
+
+Verify `<session>/artifacts/best-solution.md` exists.
+
+If missing -> AskUserQuestion (skip synthesis / retry analyst).
+
+### Step 4: Build completion summary
+
+```
+[coordinator] ============================================
+[coordinator] SWARM CONVERGED
+[coordinator]
+[coordinator] Iterations: <iterations_completed> / <max_iterations>
+[coordinator] Trigger: <triggered_by[0]>
+[coordinator] Total ants spawned: <iterations * n_ants>
+[coordinator]
+[coordinator] Best Solution:
+[coordinator]   ant_id: <best.ant_id>
+[coordinator]   iteration: <best.iteration>
+[coordinator]   path: <best.path joined with " -> ">
+[coordinator]   verified_score: <best.score>
+[coordinator]   summary: <best.candidate_solution.summary>
+[coordinator]
+[coordinator] Convergence curve (entropy):
+[coordinator]   iter 1: <e1>  iter 2: <e2>  iter 3: <e3>  ...
+[coordinator]
+[coordinator] Deliverables:
+[coordinator]   - artifacts/best-solution.md (analyst synthesis)
+[coordinator]   - artifacts/swarm-report.json (raw data)
+[coordinator]   - best.json (canonical best)
+[coordinator]   - trails/*.jsonl (full exploration log)
+[coordinator]
+[coordinator] Session: <session_path>
+[coordinator] ============================================
+```
+
+### Step 5: Update session state
+
+```
+session.status = "completed"
+session.converged_at = <iso8601>
+session.convergence_reason = <triggered_by>
+```
+
+Log state_update:
+```
+team_msg.log({
+  type: "state_update",
+  summary: "Swarm pipeline complete: <iterations_completed> iters, best=<score>",
+  data: { ... }
+})
+```
+
+### Step 6: Completion action (interactive)
+
+```
+AskUserQuestion({
+  questions: [{
+    question: "Swarm pipeline complete. What would you like to do?",
+    header: "Completion",
+    multiSelect: false,
+    options: [
+      { label: "Archive & Clean (Recommended)", description: "Archive session, delete team" },
+      { label: "Keep Active", description: "Preserve for follow-up iteration" },
+      { label: "Export Best Solution", description: "Copy best-solution.md to target path" },
+      { label: "Run Another Round", description: "Reset convergence, run K more iterations from current pheromone" }
+    ]
+  }]
+})
+```
+
+### Action Handlers
+
+| Choice | Steps |
+|--------|-------|
+| Archive & Clean | session.status = "completed"; TeamDelete; output final summary |
+| Keep Active | session.status = "paused"; output resume instructions |
+| Export Best Solution | AskUserQuestion(target path); copy best-solution.md + best.json; then Archive & Clean |
+| Run Another Round | AskUserQuestion(additional K); reset convergence counters; re-enter Phase 3 iterate.md |
+
+## Failure Cases
+
+| Failure | Action |
+|---------|--------|
+| `aco.py report` fails | Read best.json directly + manual top-K from trails/ |
+| Analyst worker crashes | Generate minimal best-solution.md from best.json template |
+| best.json missing | Pipeline ran but no successful ant - report failure, keep session for inspection |
+| Run Another Round chosen but max_iterations already at limit | AskUserQuestion to raise the cap before continuing |

package/.claude/skills/team-swarm/roles/coordinator/commands/init-swarm.md

@@ -0,0 +1,136 @@
+# Command: init-swarm
+
+Phase 2 execution guide for coordinator. Initializes swarm session and pheromone state.
+
+## Inputs
+
+- `swarm-config.json` from Phase 1 (in-memory or already written to candidate session path)
+- `session_id` already computed (`TS-<slug>-<date>`)
+- `skill_root` = `<project>/.claude/skills/team-swarm`
+
+## Workflow
+
+### Step 1: Resolve paths
+
+```
+project_root = Bash("pwd")
+skill_root = "<project_root>/.claude/skills/team-swarm"
+session_path = "<project_root>/.workflow/.team/<session_id>"
+```
+
+### Step 2: Create session directory tree
+
+```
+mkdir -p <session_path>/{pheromone/history,trails,scores,artifacts,wisdom,.msg}
+```
+
+### Step 3: Write swarm-config.json
+
+Write the Phase 1-generated config to `<session_path>/swarm-config.json`.
+
+Validate before write:
+- `task_space.nodes` OR `task_space.auto_discover_from` present
+- `swarm.n_ants` >= 2 (single-ant defeats swarm purpose)
+- `convergence.max_iterations` >= 1
+
+### Step 4: Create team
+
+```
+TeamCreate({ name: "swarm" })
+```
+
+### Step 5: Write role-binding.json
+
+```json
+{
+  "ant": "<skill_root>/roles/ant/role.md",
+  "scorer": "<skill_root>/roles/scorer/role.md",
+  "analyst": "<skill_root>/roles/analyst/role.md"
+}
+```
+
+Saved at `<session_path>/role-binding.json` — workers resolve their role.md from this file.
+
+### Step 6: Call aco.py init
+
+```
+Bash: python <skill_root>/scripts/aco.py --session <session_path> init
+```
+
+Parse stdout JSON. On `status: "error"`:
+- exit_code 2 -> config validation error -> AskUserQuestion to fix
+- exit_code 1 -> runtime error -> log to issues.md + retry once
+
+On success, capture:
+- `n_nodes` — search space size
+- `n_edges` — initial edge count
+- `pheromone_path` — confirm written
+
+### Step 7: Initialize team-session.json
+
+```json
+{
+  "session_id": "<session-id>",
+  "task_description": "<user task>",
+  "status": "active",
+  "team_name": "swarm",
+  "skill": "team-swarm",
+  "iteration": 0,
+  "max_iterations": <config.convergence.max_iterations>,
+  "n_ants_per_iter": <config.swarm.n_ants>,
+  "config_path": "swarm-config.json",
+  "pheromone_path": "pheromone/current.json",
+  "roles": ["coordinator", "ant", "scorer", "analyst"],
+  "scoring_mode": "<config.scoring.mode>",
+  "active_workers": [],
+  "completed_iterations": [],
+  "completion_action": "interactive",
+  "created_at": "<iso8601>"
+}
+```
+
+### Step 8: Initialize wisdom files
+
+Create empty wisdom files with headers:
+- `wisdom/learnings.md` — cross-iteration insights
+- `wisdom/decisions.md` — config refinements made mid-pipeline
+- `wisdom/issues.md` — errors and hallucinations log
+
+### Step 9: Log initialization state_update
+
+```
+team_msg({
+  operation: "log",
+  session_id: "<session-id>",
+  from: "coordinator",
+  type: "state_update",
+  summary: "Swarm initialized: <n_nodes> nodes, <n_ants> ants/iter, max <K> iterations",
+  data: {
+    iteration: 0,
+    n_nodes: <n>,
+    n_ants: <n>,
+    max_iterations: <K>,
+    scoring_mode: "<mode>"
+  }
+})
+```
+
+### Step 10: Proceed to Phase 3 (iterate.md)
+
+Do NOT spawn any workers in this command. First spawn happens in iterate.md step 4.
+
+## Success Criteria
+
+- `<session>/swarm-config.json` exists and validates
+- `<session>/pheromone/current.json` exists with `iteration: 0`
+- `<session>/task-space.json` exists with `n_nodes > 0`
+- team-session.json initialized with `iteration: 0`
+
+## Failure Recovery
+
+| Failure | Action |
+|---------|--------|
+| Config invalid | AskUserQuestion, regenerate, retry |
+| `aco.py init` runtime error | Log to issues.md, retry once, then AskUserQuestion (abort/refine) |
+| Directory creation fails | Check disk space / permissions, retry |
+| TeamCreate fails | Check team name conflict (existing swarm session), prompt to clean or resume |