maestro-flow 0.4.18 → 0.4.19

package/.agents/skills/team-swarm/specs/convergence-criteria.md

@@ -0,0 +1,106 @@
+# Convergence Criteria
+
+When does the swarm stop iterating? Defines stop conditions computed by `aco.py converged`.
+
+## Stop Conditions (any-of)
+
+The swarm stops when **any** of the configured criteria triggers:
+
+| Criterion | Default | Description |
+|-----------|---------|-------------|
+| `max_iterations` | 5 | Hard cap on iteration count |
+| `stagnation` | patience = 2 | Best score unchanged for N iterations |
+| `entropy_floor` | 0.5 | Pheromone Shannon entropy drops below threshold (matrix highly concentrated) |
+| `budget_tokens` | 100000 | Total token cost exceeds budget |
+| `target_score` | 0.95 | Best verified_score crosses target |
+
+## Configuration
+
+```json
+{
+  "convergence": {
+    "max_iterations": 5,
+    "stagnation": { "enabled": true, "patience": 2, "min_delta": 0.01 },
+    "entropy_floor": { "enabled": true, "threshold": 0.5 },
+    "budget_tokens": { "enabled": false, "max": 100000 },
+    "target_score": { "enabled": true, "value": 0.95 }
+  }
+}
+```
+
+## Output Schema (aco.py converged)
+
+```json
+{
+  "converged": true,
+  "iteration": 4,
+  "reason": "stagnation",
+  "metrics": {
+    "best_score": 0.78,
+    "mean_score": 0.62,
+    "entropy": 1.85,
+    "iterations_completed": 4,
+    "iterations_since_best_change": 2,
+    "total_tokens_used": 42000
+  },
+  "triggered_by": ["stagnation"],
+  "recommendation": "best solution is stable; recommend report"
+}
+```
+
+## Selection Logic
+
+```
+def check_convergence(history, config):
+    triggered = []
+    
+    if iteration >= config.max_iterations:
+        triggered.append("max_iterations")
+    
+    if config.stagnation.enabled:
+        recent = history[-config.stagnation.patience-1:]
+        if len(recent) > config.stagnation.patience:
+            deltas = [abs(recent[i].best - recent[i-1].best) 
+                      for i in range(1, len(recent))]
+            if all(d < config.stagnation.min_delta for d in deltas):
+                triggered.append("stagnation")
+    
+    if config.entropy_floor.enabled and current_entropy < threshold:
+        triggered.append("entropy_floor")
+    
+    if config.budget_tokens.enabled and total_tokens > config.budget_tokens.max:
+        triggered.append("budget_tokens")
+    
+    if config.target_score.enabled and best_score >= config.target_score.value:
+        triggered.append("target_score")
+    
+    return {"converged": len(triggered) > 0, "triggered_by": triggered}
+```
+
+## Entropy Calculation
+
+Shannon entropy of normalized pheromone distribution:
+
+```
+p_i = tau_i / sum(tau)  for each active edge
+H = -sum(p_i * log2(p_i))
+```
+
+- High H → diverse exploration (early stage)
+- Low H → concentrated on few paths (converging)
+- H < threshold + best score plateau → safe to stop
+
+## Why Multi-Criterion
+
+Single criterion is fragile:
+- `max_iterations` alone wastes budget if converged early
+- `stagnation` alone may stop too early on noisy scoring
+- `entropy_floor` alone may trigger before useful solutions emerge
+
+Combination = early termination when safe, but always bounded by `max_iterations`.
+
+## Anti-Patterns
+
+- DO NOT use `stagnation` with `patience < 2` — noise will trigger false stops
+- DO NOT disable `max_iterations` — runaway risk
+- DO NOT set `target_score` without verified scoring — self_score is too optimistic

package/.agents/skills/team-swarm/specs/pheromone-schema.md

@@ -0,0 +1,123 @@
+# Pheromone Schema
+
+Pheromone matrix structure, update formula, evaporation rule. Authoritative spec for `pheromone/current.json` and history snapshots.
+
+## File Layout
+
+```
+<session>/pheromone/
+├── current.json         # latest state, overwritten each iteration
+├── history/
+│   ├── 1.json           # snapshot after iteration 1
+│   ├── 2.json
+│   └── ...
+└── init.json            # snapshot of initial state (immutable)
+```
+
+## Schema (pheromone/current.json)
+
+```json
+{
+  "version": "1.0",
+  "iteration": 3,
+  "n_nodes": 42,
+  "matrix_type": "edge_weighted_sparse",
+  "tau": {
+    "<node_a>::<node_b>": 0.85,
+    "<node_a>::<node_c>": 1.20,
+    "<node_x>::<node_y>": 0.13
+  },
+  "node_tau": {
+    "<node_a>": 0.92,
+    "<node_b>": 1.05
+  },
+  "metadata": {
+    "alpha": 1.0,
+    "beta": 2.0,
+    "rho": 0.2,
+    "q": 1.0,
+    "tau_init": 1.0,
+    "tau_min": 0.01,
+    "tau_max": 10.0
+  },
+  "stats": {
+    "mean": 0.91,
+    "max": 2.34,
+    "min": 0.05,
+    "entropy": 3.21,
+    "n_edges_active": 87
+  }
+}
+```
+
+### Field Semantics
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `matrix_type` | enum | `edge_weighted_sparse` (default), `node_weighted`, `full_dense` |
+| `tau` | dict | Edge pheromone, key `"a::b"` (undirected uses lexical order) |
+| `node_tau` | dict | Node-level pheromone (used when matrix_type = node_weighted) |
+| `metadata.alpha` | float | Pheromone weight in selection probability |
+| `metadata.beta` | float | Heuristic weight in selection probability |
+| `metadata.rho` | float | Evaporation rate (0..1), applied each iteration |
+| `metadata.q` | float | Deposit constant |
+| `metadata.tau_min/max` | float | MMAS bounds — prevents premature convergence/explosion |
+| `stats.entropy` | float | Shannon entropy of normalized tau — convergence signal |
+
+## Update Formula
+
+After iteration k completes, for each ant a in iteration:
+
+```
+delta_tau_a(edge) = q * verified_score_a  if edge in path_a, else 0
+```
+
+Then:
+
+```
+tau(edge) = (1 - rho) * tau(edge) + sum_over_ants(delta_tau_a(edge))
+tau(edge) = clip(tau(edge), tau_min, tau_max)
+```
+
+**Elitist strategy** (always on): the best path of all time deposits extra `q * best_score` on its edges before clipping.
+
+## Selection Probability (used in `aco.py select`)
+
+For ant at node i choosing neighbor j from candidate set N(i):
+
+```
+p(i -> j) = (tau(i,j)^alpha * eta(i,j)^beta) / sum_{k in N(i)}(tau(i,k)^alpha * eta(i,k)^beta)
+```
+
+where `eta` is a heuristic value from config (e.g., inverse-distance, prior knowledge). Default `eta = 1.0` if not provided.
+
+## Path-Hints vs Full-Path
+
+`aco.py select` does NOT prescribe a complete path — it returns **path-hints**: weighted starting nodes + edge probabilities. The ant (LLM) then makes the actual node-by-node choices, with freedom to deviate based on its own evidence. This preserves LLM judgment while keeping search guided.
+
+```json
+{
+  "ant_id": "ANT-3-2",
+  "start_node": "node_a",
+  "edge_preferences": {
+    "node_a::node_b": 0.45,
+    "node_a::node_c": 0.30,
+    "node_a::node_d": 0.25
+  },
+  "max_path_length": 5
+}
+```
+
+## Initialization
+
+```
+tau_init for all edges = config.aco.tau_init (default 1.0)
+```
+
+If `task_space.nodes` is `auto_discover_from: <glob>`, init.py discovers nodes by globbing and initializes a full uniform matrix.
+
+## History & Reproducibility
+
+- `init.json` — frozen snapshot of initial state (never overwritten)
+- `history/k.json` — full pheromone state after iteration k (for convergence-curve analysis)
+- All updates are deterministic given (prior state + ant artifacts + config)

package/.agents/skills/team-swarm/specs/swarm-config-template.json

@@ -0,0 +1,71 @@
+{
+  "_comment": "User-facing config template. Coordinator generates this from task description in Phase 1. Fields prefixed with _ are documentation, omit from real config.",
+
+  "swarm": {
+    "_comment": "Top-level swarm parameters",
+    "n_ants": 5,
+    "max_iterations": 5,
+    "elite_keep": 3
+  },
+
+  "aco": {
+    "_comment": "ACO algorithm hyperparameters - defaults are sane",
+    "alpha": 1.0,
+    "beta": 2.0,
+    "rho": 0.2,
+    "q": 1.0,
+    "tau_init": 1.0,
+    "tau_min": 0.01,
+    "tau_max": 10.0
+  },
+
+  "task_space": {
+    "_comment": "Define the search space. Use EITHER 'nodes' (explicit) OR 'auto_discover_from' (glob).",
+    "type": "graph",
+    "nodes": ["node_a", "node_b", "node_c"],
+    "_alt_auto_discover": "auto_discover_from: 'src/**/*.ts'",
+    "max_path_length": 5,
+    "start_nodes": "any",
+    "edges": "complete"
+  },
+
+  "scoring": {
+    "_comment": "How verified_score is computed. mode = script | llm | fallback",
+    "mode": "fallback",
+    "_alt_script": "script_path: '../my-scoring-rule.py' (file must define def score(ant_artifact) -> float)",
+    "_alt_llm": "rubric: 'custom scoring rubric text for scorer role'",
+    "self_score_discount": 0.5
+  },
+
+  "ant_prompt": {
+    "_comment": "What the ant actually tries to achieve. This is the bridge between task semantics and ACO mechanics.",
+    "objective": "Find the file with the highest density of suspicious code patterns",
+    "evidence_requirements": [
+      "At least 1 file:line reference per node visited",
+      "Concrete code snippet showing the suspicious pattern"
+    ],
+    "tools_hint": "Use Grep + Read for code-based exploration"
+  },
+
+  "convergence": {
+    "_comment": "Stop conditions - any-of triggers convergence",
+    "max_iterations": 5,
+    "stagnation": {
+      "enabled": true,
+      "patience": 2,
+      "min_delta": 0.01
+    },
+    "entropy_floor": {
+      "enabled": true,
+      "threshold": 0.5
+    },
+    "budget_tokens": {
+      "enabled": false,
+      "max": 100000
+    },
+    "target_score": {
+      "enabled": true,
+      "value": 0.95
+    }
+  }
+}

package/.agents/skills/team-swarm/specs/swarm-protocol.md

@@ -0,0 +1,117 @@
+# Swarm Protocol
+
+Master protocol document for team-swarm: defines how the LLM coordinator and Python ACO controller interface, how ants explore the task space, and how exploration results flow back to update pheromone state.
+
+## Design Philosophy
+
+| Principle | Rationale |
+|-----------|-----------|
+| **Outer loop = script, inner loop = LLM** | Optimization math is cheap and deterministic; LLM evaluation is expensive and noisy. Separate them. |
+| **Coordinator is a hybrid** | LLM coordinator translates user intent + dispatches workers; Python script makes all numeric decisions (selection, update, convergence). |
+| **Schema-locked ant output** | LLM output → algorithm input bridge demands strict JSON contract. Free-text outputs cannot feed pheromone updates. |
+| **Two-layer scoring** | `self_score` (LLM self-report) is fast but optimistic. `verified_score` (script or LLM scorer) is the only authoritative input to pheromone update. |
+| **Universal task space** | Coordinator does not bake in any domain. User provides `swarm-config.json` with task space + scoring rule. |
+
+## Three-Component Architecture
+
+```
++-----------------------------------------------------+
+|  LLM Coordinator (roles/coordinator/role.md)       |
+|  - Parses user task → emits swarm-config.json       |
+|  - Phase 3 main loop: calls script, spawns workers  |
+|  - Translates worker callbacks back into script ops |
++--------+--------------------------------------------+
+         | Bash subprocess
+         v
++-----------------------------------------------------+
+|  Python ACO Controller (scripts/aco.py)            |
+|  - CLI subcommands: init/select/update/converged    |
+|  - Owns pheromone matrix + elite tracker            |
+|  - Pure functions of session state files            |
++-----------------------------------------------------+
+         ^                                  |
+         | reads artifacts/ant-*.json       | writes pheromone/*.json
+         |                                  v
++-----------------------------------------------------+
+|  LLM Workers (team-worker agents)                  |
+|  - ant: explores assigned path, writes JSON         |
+|  - scorer: assigns verified_score (optional)        |
+|  - analyst: final synthesis of elite solutions      |
++-----------------------------------------------------+
+```
+
+## Iteration Lifecycle
+
+```
+[Coordinator] init phase
+  └─> python aco.py init --config <session>/swarm-config.json
+       └─> writes pheromone/current.json + task-space.json
+
+[Coordinator] iteration k (k = 1..K):
+  ├─> python aco.py select --iter k
+  │    └─> returns N ant assignments (paths to explore)
+  ├─> create_task × N ant tasks
+  ├─> spawn N × team-worker(ant) in background
+  └─> STOP (await all callbacks)
+  
+[Callback] all ants done → handleIterationComplete
+  ├─> (optional) spawn scorer worker → verified_scores.json
+  ├─> python aco.py update --iter k
+  │    └─> reads artifacts/ant-k-*.json + verified_scores
+  │    └─> updates pheromone + elite + history
+  ├─> python aco.py converged
+  │    └─> {converged: true|false, reason: ...}
+  └─> converged → Phase 4; else → iteration k+1
+
+[Coordinator] Phase 4: converge
+  ├─> python aco.py report → best.json
+  ├─> spawn analyst worker → best-solution.md
+  └─> completion action (Archive/Keep/Export)
+```
+
+## Script ↔ Coordinator Contract
+
+All scripts MUST:
+- Read from `<session>/...` (session path passed via `--session` flag)
+- Write JSON to stdout for coordinator parsing (no prose)
+- Use exit code 0 = success, 1 = error, 2 = config invalid
+- Be idempotent: calling `update` twice for same iteration is safe
+
+| Subcommand | Input | Output (stdout JSON) | Side effects |
+|------------|-------|---------------------|--------------|
+| `init` | swarm-config.json | `{status, pheromone_path, n_nodes}` | writes pheromone/current.json, task-space.json |
+| `select --iter k` | pheromone/current.json, swarm-config.json | `{iteration, assignments: [{ant_id, path_hints, ...}]}` | none |
+| `update --iter k` | artifacts/ant-k-*.json, optional verified_scores.json | `{iteration, mean_score, best_score, delta, elite_updated}` | writes pheromone/current.json (overwrite) + pheromone/history/k.json + trails/k.jsonl + best.json |
+| `converged` | history/, best.json, config | `{converged: bool, reason: str, metrics: {...}}` | none |
+| `report` | best.json, history/ | full JSON: `{best, top_k, convergence_curve, ...}` | none |
+
+## Data Flow Boundaries
+
+| Boundary | Owner | Format |
+|----------|-------|--------|
+| User intent → config | LLM coordinator | swarm-config.json |
+| Pheromone state | Python script | pheromone/current.json |
+| Ant assignment → ant prompt | LLM coordinator (templated) | injected into role-spec at spawn |
+| Ant exploration → artifact | LLM ant | artifacts/ant-k-id.json (schema-locked) |
+| Artifact → pheromone update | Python script | reads artifacts, computes delta tau |
+| Elite solutions → human report | LLM analyst | artifacts/best-solution.md |
+
+## Why Hybrid Coordinator (Not Pure Script)
+
+- User input is natural language → needs LLM to map to swarm-config
+- Worker spawning, message routing, session management → all framework-bound to LLM coordinator
+- Script as a sub-tool keeps the same team-* lifecycle (spawn-and-stop, callback-driven)
+- Same pattern as `maestro delegate` — Bash-callable subprocess from inside an LLM role
+
+## Universality
+
+`team-swarm` is task-agnostic. Specialization happens via:
+1. `swarm-config.json#task_space` — defines what nodes/edges/paths mean
+2. `swarm-config.json#scoring` — defines how to compute verified_score
+3. `swarm-config.json#ant_prompt` — defines what ant should actually do at each node
+
+Example domains the same skill handles:
+- Code exploration (nodes = files/modules, score = suspicious code density)
+- Test case generation (nodes = code paths, score = coverage delta)
+- Refactor strategy search (nodes = refactor moves, score = complexity reduction)
+- Hyperparameter tuning (nodes = param choices, score = metric improvement)