maestro-flow 0.4.17 → 0.4.19

package/.claude/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/.claude/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/.claude/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/.claude/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)
+  ├─> TaskCreate × 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)

package/.codex/skills/learn-decompose/SKILL.md

@@ -54,7 +54,7 @@ Resolve target to file list. Load coding specs: `maestro spec load --category co
 
 ### Phase 2: Wave 1 — Parallel Dimension Scans
 
-Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2). Initialize every row with `status="pending"`. Filter `wave==N AND status=="pending"` when writing each wave CSV.
 
 | id | dimension | focus |
 |----|-----------|-------|
@@ -64,7 +64,38 @@ Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
 | 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
 | 5 | cross-ref | Dedup + catalog from wave 1 findings |
 
-Each dimension agent returns:
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "dimension":     { "type": "string", "enum": ["structural", "behavioral", "data", "error", "cross-ref"] },
+    "patterns":      { "type": "string", "description": "JSON array string: [{name, dimension, confidence, anchors, description, rationale, tradeoffs}]" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `dimension`, `patterns`, `findings`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (patterns may be empty array if nothing found)
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=completed with partial patterns
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Every finding MUST include file:line anchors. No speculation.
+- Read-only analysis. Do NOT modify source.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+Each dimension agent populates `patterns` as a JSON array string of:
 ```json
 [{
   "name": "pattern name",
@@ -79,7 +110,7 @@ Each dimension agent returns:
 
 ### Phase 3: Wave 2 — Cross-Reference + Catalog
 
-Single agent receives all wave 1 findings via `prev_context`. Tasks:
+Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
 - Match against dedup set → mark as `documented`, `known`, or `new`
 - Merge duplicates across dimensions (same pattern found by multiple agents)
 - Flag contradictions with documented conventions

package/.codex/skills/learn-retro/SKILL.md

@@ -44,7 +44,7 @@ $ARGUMENTS — lens selection and scope flags.
 **3a: Collect decisions** from wiki, specs, git log, phase context, .workflow/specs/learnings.md.
 **3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
 
-**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
+**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents; filter `wave==1 AND status=="pending"`):
 
 | id | perspective | focus |
 |----|------------|-------|
@@ -52,6 +52,36 @@ $ARGUMENTS — lens selection and scope flags.
 | 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
 | 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
 
+**output_schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "perspective":   { "type": "string", "enum": ["technical", "cost", "hindsight"] },
+    "grade":         { "type": "string" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "grade", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `perspective`, `grade`, `findings`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed with concrete grade
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only analysis. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 **3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
 
 ### Phase 4: Unified Report

package/.codex/skills/learn-second-opinion/SKILL.md

@@ -47,12 +47,42 @@ Resolve target to content. Load specs, wiki search, prior lessons for context br
 | 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
 | 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
 
-Wave 1: 3 persona agents in parallel. Wave 2: synthesis agent with wave 1 findings as prev_context.
-
-Each persona returns: `{ persona, verdict: approve|concern|reject, confidence, findings: [{severity, description, location, suggestion}], summary }`
+Wave 1: 3 persona agents in parallel (filter `wave==1 AND status=="pending"`). Wave 2: synthesis agent with wave 1 findings as prev_context.
+
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "persona":       { "type": "string" },
+    "verdict":       { "type": "string", "enum": ["approve", "concern", "reject", ""] },
+    "confidence":    { "type": "string", "description": "0-100" },
+    "findings":      { "type": "string", "description": "JSON array of {severity, description, location, suggestion}, max 500 chars summary" },
+    "summary":       { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "summary"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `persona`, `verdict`, `confidence`, `findings`, `summary`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed with concrete verdict
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only analysis. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 #### Challenge Mode
-Single agent via spawn_agents_on_csv (1 worker). Adversarial analysis with forcing questions:
+Single agent via spawn_agents_on_csv (max_concurrency: 1) with the same `output_schema` + termination contract above. Adversarial analysis with forcing questions:
 - "What assumption would invalidate this entire approach?"
 - "What's the simplest thing that breaks this?"
 - "What's the implicit contract that isn't enforced?"

package/.codex/skills/maestro-analyze/SKILL.md

@@ -152,29 +152,63 @@ S_AGGREGATE:
 
 <actions>
 
+### Shared Spawn Contract (all three waves)
+
+Every `spawn_agents_on_csv` call in this skill MUST use the strict JSON Schema below and the shared termination contract.
+
+**Output Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "score":         { "type": "string", "description": "0-100 (wave 2 scoring only)" },
+    "evidence":      { "type": "string", "description": "Code refs file:line (wave 1/2)" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge step: `result_status` → master `status`; copy `findings`, `score`, `evidence`, `error`.
+
+**Termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed
+- Failure → result_status=failed with error message
+- Blocked → upstream missing → result_status=blocked
+- Timeout → near max_runtime_seconds → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 ### A_SPAWN_WAVE_1
 
-Filter wave==1 -> write wave-1.csv -> `spawn_agents_on_csv({ csv_path, max_concurrency })`.
+Filter `wave==1 AND status=="pending"` -> write wave-1.csv -> `spawn_agents_on_csv({ csv_path, id_column:"id", instruction: EXPLORATION_INSTRUCTION + SHARED_TERMINATION_CONTRACT, max_concurrency, max_runtime_seconds: 3600, output_csv_path, output_schema })`.
 
 **Exploration agent** (3-layer per dimension):
 1. Module Discovery (breadth): keyword search, relevant files, module boundaries
 2. Structure Tracing (depth): top 3-5 files, call chains 2-3 levels, data flow
 3. Code Anchor Extraction (detail): code snippet 20-50 lines with file:line per finding
 
-Share via discovery board. Merge results -> master tasks.csv.
+Share via discovery board. Merge results -> master tasks.csv (map `result_status` → master `status`).
 
 ### A_SPAWN_WAVE_2
 
-Filter wave==2 -> build prev_context from wave 1 findings -> write wave-2.csv -> spawn.
+Filter `wave==2 AND status=="pending"` -> build prev_context from wave 1 findings -> write wave-2.csv -> spawn with `SCORING_INSTRUCTION + SHARED_TERMINATION_CONTRACT`.
 
 **Scoring agent** (6 dimensions: feasibility, impact, risk, complexity, alignment, maintainability):
 Score 0-100 with specific evidence (code refs from exploration). Each score MUST reference exploration findings.
 
-Merge results -> master tasks.csv.
+Merge results -> master tasks.csv (map `result_status` → master `status`).
 
 ### A_SPAWN_WAVE_3
 
-Filter wave==3 -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn.
+Filter `wave==3 AND status=="pending"` -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn with `SYNTHESIS_INSTRUCTION + SHARED_TERMINATION_CONTRACT`.
 
 **Synthesis agent**:
 - Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), context-package.json, conclusions.json (with `scope_verdict` + `implementation_scope[]`)
@@ -262,5 +296,10 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Upstream context loaded via `--from` when specified
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
+- [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+</on_complete>
 </output>

package/.codex/skills/maestro-blueprint/SKILL.md

@@ -120,4 +120,9 @@ P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail
 - [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
 - [ ] Artifact registered in state.json (type=blueprint)
 - [ ] context-package.json generated for downstream consumption
+- [ ] On gate Pass/Review: session sealed via finish-work (archive.json + optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={session_dir}, SESSION_TYPE=blueprint, SESSION_ID={session_id}, LINKED_MILESTONE=null
+</on_complete>