maestro-flow 0.4.16 → 0.4.18

package/.codex/skills/quality-review/SKILL.md

@@ -216,33 +216,69 @@ Filter master `tasks.csv` for `wave == 1 AND status == pending` → write `wave-
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
-  instruction: buildReviewInstruction(sessionFolder),  // agent: ~/.codex/agents/workflow-reviewer.toml
+  instruction: REVIEW_DIMENSION_INSTRUCTION,    // see "Dimension Worker Contract" below
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
   output_schema: {
     type: "object",
     properties: {
-      id: { type: "string" },
-      result_status: { type: "string", enum: ["completed", "failed"] },
-      findings: { type: "string" },
-      severity_counts: { type: "string" },
-      top_issues: { type: "string" },
-      error: { type: "string" }
+      id:              { type: "string" },
+      result_status:   { type: "string", enum: ["completed", "failed"] },
+      findings:        { type: "string", maxLength: 500 },
+      severity_counts: { type: "string", description: "JSON object string {critical, high, medium, low}" },
+      top_issues:      { type: "string", description: "JSON array string of top issues with file:line" },
+      error:           { type: "string" }
     },
     required: ["id", "result_status", "findings"]
   }
 })
 ```
 
-Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` → master `status` column), then delete both `wave-1.csv` and `wave-1-results.csv`.
+Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` → master `status` column; copy `findings`, `severity_counts`, `top_issues`, `error`), then delete both `wave-1.csv` and `wave-1-results.csv`.
+
+#### Dimension Worker Contract (REVIEW_DIMENSION_INSTRUCTION)
+
+```
+You are a code reviewer for ONE dimension (correctness/security/performance/maintainability/...). Your dimension, scope, and standards come from your CSV row.
+
+REQUIRED STEPS:
+  1. Read shared discoveries: {sessionFolder}/discoveries.ndjson
+  2. Read specs loaded by orchestrator (review category) for severity calibration
+  3. Scan code in scope using Read/Grep/Glob (read-only)
+  4. Classify each issue: critical / high / medium / low with file:line refs
+  5. Append cross-cutting patterns to discoveries.ndjson
+  6. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success → result_status=completed (severity_counts may be all-zero if clean)
+  - Timeout → near max_runtime_seconds, STOP and report completed with partial findings
+  - Failure → unrecoverable read/parse error → result_status=failed
+  - NEVER skip report_agent_job_result.
+
+OUTPUT (must match output_schema):
+  {
+    "id": "<your row id>",
+    "result_status": "completed" | "failed",
+    "findings": "<one-sentence dimension summary, max 500 chars>",
+    "severity_counts": "<JSON object string: {critical:N, high:N, medium:N, low:N}>",
+    "top_issues": "<JSON array string: [{title, severity, location, recommendation}...]>",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Every issue MUST have a concrete file:line reference. No speculation.
+  - Do NOT modify source. This is review only.
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv, review.json (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 #### Wave 2: Aggregation + Deep-Dive
 
 Filter master `tasks.csv` for `wave == 2 AND status == pending`. If all wave 1 tasks failed, skip aggregation.
 
 Build `prev_context` from wave 1 findings (format: `[Task N: Title] summary...` per task).
-Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` → merge results into master `tasks.csv` (map `result_status` → master `status` column) → delete both `wave-2.csv` and `wave-2-results.csv`.
+Write `wave-2.csv` with `prev_context` column → execute `spawn_agents_on_csv` with `REVIEW_AGGREGATION_INSTRUCTION` (same termination contract; output_schema returns `result_status` enum [completed|failed], findings, plus `verdict` enum [PASS|WARN|BLOCK]) → merge results into master `tasks.csv` (map `result_status` → master `status` column) → delete both `wave-2.csv` and `wave-2-results.csv`.
 
 ### Phase 3: Results Aggregation
 

package/.codex/skills/quality-test/SKILL.md

@@ -183,10 +183,65 @@ On issue: auto-create in `.workflow/issues/issues.jsonl`:
 ### A_DIAGNOSE_GAPS
 
 1. Cluster gaps by component/module/feature
-2. Build diagnosis.csv: one row per gap with target_files, source_context
-3. `spawn_agents_on_csv` for parallel diagnosis
+2. Build diagnosis.csv with `status="pending"` per row, target_files, source_context
+3. Filter `status=="pending"` -> write diagnosis-wave.csv -> `spawn_agents_on_csv` for parallel diagnosis with the contract below
 4. **Diagnosis agent**: Find root cause (not symptom), suggest fix direction, list affected files. Do NOT modify files. Reference issue_id for traceability.
-5. Merge results: update uat.md gaps with root_cause, fix_direction, affected_files
+5. Merge results: map `result_status` → master `status`; copy `root_cause`, `fix_direction`, `affected_files`; update uat.md gaps
+
+**output_schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":              { "type": "string" },
+    "result_status":   { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "root_cause":      { "type": "string", "maxLength": 500 },
+    "fix_direction":   { "type": "string" },
+    "affected_files":  { "type": "string", "description": "Semicolon-separated file:line refs" },
+    "findings":        { "type": "string", "maxLength": 500 },
+    "error":           { "type": "string" }
+  },
+  "required": ["id", "result_status", "root_cause", "findings"]
+}
+```
+
+**Diagnosis Worker Instruction** (embed in spawn instruction):
+```
+You are a UAT gap diagnostician. ONE gap row is assigned to you.
+
+INPUT: id, target_files, source_context, issue_id, gap description
+
+REQUIRED STEPS:
+  1. Read target_files + source_context (read-only)
+  2. Trace symptom backward through call chain to root cause
+  3. Identify fix direction (high-level — orchestrator hands off to maestro-plan)
+  4. List affected files with file:line refs
+  5. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory):
+  - Success → result_status=completed with root_cause + fix_direction populated
+  - Failure → result_status=failed (cannot read files, parse error)
+  - Blocked → result_status=blocked (insufficient context to diagnose; orchestrator may re-cluster)
+  - Timeout → near max_runtime_seconds → result_status=blocked with error="timeout"
+  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+OUTPUT (must match output_schema):
+  {
+    "id": "<your row id>",
+    "result_status": "completed" | "failed" | "blocked",
+    "root_cause": "<concrete root cause with file:line, max 500 chars>",
+    "fix_direction": "<high-level fix strategy, NOT code>",
+    "affected_files": "<semicolon-separated file:line refs>",
+    "findings": "<one-sentence summary>",
+    "error": "<message if not completed>"
+  }
+
+CONSTRAINTS:
+  - Read-only. Do NOT modify source files.
+  - Do NOT write to uat.md, diagnosis.csv, issues.jsonl (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 ### A_GAP_FIX_LOOP
 

package/.codex/skills/security-audit/SKILL.md

@@ -59,6 +59,38 @@ Use `Grep` for pattern matching (e.g., `eval(`, `exec(`, `innerHTML`, `dangerous
 For `standard` and `deep` tiers, use `spawn_agents_on_csv` to parallelize OWASP category scans
 across multiple agents, one agent per 2-3 categories.
 
+**spawn_agents_on_csv contract** (OWASP scan):
+- CSV columns: `id, title, owasp_categories, scope_glob, deps, wave, status` (initial `status="pending"`); filter `wave==1 AND status=="pending"` before writing wave-1.csv.
+- `output_schema`:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":              { "type": "string" },
+    "result_status":   { "type": "string", "enum": ["completed", "failed"] },
+    "findings":        { "type": "string", "maxLength": 500 },
+    "severity_counts": { "type": "string", "description": "JSON: {critical, high, medium, low}" },
+    "top_issues":      { "type": "string", "description": "JSON array: [{title, severity, file:line, cwe}]" },
+    "error":           { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+- Merge: `result_status` → master `status`; copy `findings`, `severity_counts`, `top_issues`, `error`.
+- **Termination contract** (embed in instruction):
+  ```
+  You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+  - Success → result_status=completed (severity_counts may be zero if clean)
+  - Failure → result_status=failed with error message
+  - Timeout → near max_runtime_seconds → result_status=completed with partial top_issues (do not fail the wave for timeout)
+  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+  - Every issue MUST include file:line and CWE reference. No speculation.
+  - Read-only. Do NOT modify source.
+  Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+  ```
+
 **Phase 3: Dependency Audit** (all tiers)
 
 ```bash
@@ -107,6 +139,12 @@ For each critical module identified in Phase 1:
 For `deep` tier, use `spawn_agents_on_csv` to parallelize STRIDE analysis across critical modules,
 one agent per module. Use `request_user_input` to confirm critical module list before spawning.
 
+**STRIDE spawn contract**:
+- CSV columns: `id, module_path, threats_to_assess, deps, wave, status` (initial `status="pending"`); filter `wave==2 AND status=="pending"`.
+- Same `output_schema` as the OWASP spawn above, but `top_issues` JSON items use shape `{stride_category, threat, severity, file:line, mitigation}`.
+- Same termination contract as the OWASP spawn above (mandatory `report_agent_job_result`, read-only, no recursion, timeout → partial findings, etc.).
+- Merge: `result_status` → master `status`; copy `findings`, `severity_counts`, `top_issues`, `error`.
+
 **Phase 7: Git History Archaeology** (deep only)
 
 ```bash

package/.codex/skills/spec-map/SKILL.md

@@ -61,10 +61,10 @@ $spec-map --continue "20260318-map-auth"
 
 ```csv
 id,title,description,focus_area,output_file,deps,context_from,wave,status,findings,error
-"1","Tech Stack Analysis","Analyze languages, frameworks, dependencies, build system, package managers, runtime configuration. Scan package.json, build configs, CI/CD files.","full","tech-stack.md","","","1","","",""
-"2","Architecture Analysis","Analyze project structure, module boundaries, layer architecture, data flow patterns, entry points, API surface. Map directory tree and import graph.","full","architecture.md","","","1","","",""
-"3","Features Analysis","Inventory user-facing capabilities, API endpoints, CLI commands, UI components, background jobs, integrations. Map to source locations.","full","features.md","","","1","","",""
-"4","Cross-cutting Concerns","Analyze error handling patterns, logging strategy, authentication/authorization, configuration management, testing approach, observability.","full","concerns.md","","","1","","",""
+"1","Tech Stack Analysis","Analyze languages, frameworks, dependencies, build system, package managers, runtime configuration. Scan package.json, build configs, CI/CD files.","full","tech-stack.md","","","1","pending","",""
+"2","Architecture Analysis","Analyze project structure, module boundaries, layer architecture, data flow patterns, entry points, API surface. Map directory tree and import graph.","full","architecture.md","","","1","pending","",""
+"3","Features Analysis","Inventory user-facing capabilities, API endpoints, CLI commands, UI components, background jobs, integrations. Map to source locations.","full","features.md","","","1","pending","",""
+"4","Cross-cutting Concerns","Analyze error handling patterns, logging strategy, authentication/authorization, configuration management, testing approach, observability.","full","concerns.md","","","1","pending","",""
 ```
 
 **Columns**:
@@ -79,9 +79,11 @@ id,title,description,focus_area,output_file,deps,context_from,wave,status,findin
 | `deps` | Input | Empty (all independent) |
 | `context_from` | Input | Empty (no cross-task context) |
 | `wave` | Computed | Always 1 (single wave) |
-| `status` | Output | pending/completed/failed/skipped |
-| `findings` | Output | Analysis summary (max 500 chars) |
-| `error` | Output | Error if failed |
+| `status` | Lifecycle | `pending` (initial) → `completed`/`failed`/`skipped` (set by merge step from worker's `result_status`) |
+| `findings` | Lifecycle | Analysis summary (max 500 chars; merged from worker output) |
+| `error` | Lifecycle | Error if failed (merged) |
+
+**Column separation rule**: Wave CSV (input to `spawn_agents_on_csv`) contains Input columns only. Workers return Output columns exclusively via `output_schema` using `result_status` (NOT `status`). Merge maps `result_status` → master `status`.
 
 </csv_schema>
 
@@ -106,7 +108,62 @@ Generate 4 mapper rows. If focus area specified, scope descriptions to that area
 
 ### Phase 2: Wave Execution
 
-Single wave -- all 4 mappers via `spawn_agents_on_csv` (max_concurrency: 4, 3600s timeout). Each agent returns: id, status (completed/failed), findings, error.
+Single wave -- all 4 mappers via `spawn_agents_on_csv`:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-1.csv`,       // only rows where status == "pending"
+  id_column: "id",
+  instruction: MAPPER_INSTRUCTION,                // see "Mapper Worker Contract" below
+  max_concurrency: 4,
+  max_runtime_seconds: 3600,
+  output_csv_path: `${sessionFolder}/wave-1-results.csv`,
+  output_schema: {
+    type: "object",
+    properties: {
+      id:            { type: "string" },
+      result_status: { type: "string", enum: ["completed", "failed"] },
+      findings:      { type: "string", maxLength: 500 },
+      error:         { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
+  }
+})
+```
+
+Merge: write `master.status = result_status`, copy `findings` and `error`. Delete `wave-1.csv` and `wave-1-results.csv`.
+
+#### Mapper Worker Contract (MAPPER_INSTRUCTION)
+
+```
+You are a codebase mapper for ONE dimension. Your assigned focus_area, description, and output_file come from your CSV row.
+
+REQUIRED STEPS:
+  1. Read shared discoveries: {sessionFolder}/discoveries.ndjson (may be empty)
+  2. Scan codebase using Read/Grep/Glob within your focus_area
+  3. Synthesize findings into the analysis sections required by your description
+  4. Append reusable discoveries (tech_stack / code_pattern / integration_point / convention) to discoveries.ndjson
+  5. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success path → result_status = completed
+  - Timeout path → if approaching max_runtime_seconds, STOP and report failed with error="timeout (partial findings)"
+  - Failure path → on unrecoverable error, report failed with error message
+  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+OUTPUT (return via report_agent_job_result; must match output_schema):
+  {
+    "id": "<your row id>",
+    "result_status": "completed" | "failed",
+    "findings": "<analysis summary, max 500 chars — orchestrator uses this to write {output_file}>",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Read-only. Do NOT write to .workflow/codebase/ — orchestrator writes output files from your findings in Phase 3.
+  - Do NOT write to tasks.csv, wave-*.csv, or results.csv.
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 ### Phase 3: Write Output Files
 

package/.codex/skills/team-coordinate/SKILL.md

@@ -303,18 +303,22 @@ Extract qualifying rows from master CSV. Add `prev_context` column.
 
 ```javascript
 spawn_agents_on_csv({
-  csv_path: `${sessionFolder}/wave-${N}.csv`,
+  csv_path: `${sessionFolder}/wave-${N}.csv`,    // only rows where wave==N AND status=="pending"
   id_column: "id",
-  instruction: /* see Instruction Builder section below */,
+  instruction: TEAM_COORDINATE_INSTRUCTION,       // see "Instruction Builder" section below
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
   output_schema: {
-    id,              // mandatory: links to master CSV
-    result_status,   // mandatory: completed | failed | blocked
-    findings,        // key findings (max 500 chars)
-    files_modified,  // semicolon-separated paths
-    error            // error message if not completed
+    type: "object",
+    properties: {
+      id:             { type: "string" },
+      result_status:  { type: "string", enum: ["completed", "failed", "blocked"] },
+      findings:       { type: "string", maxLength: 500 },
+      files_modified: { type: "string", description: "Semicolon-separated paths" },
+      error:          { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
   }
 })
 ```
@@ -409,12 +413,25 @@ Append findings as NDJSON lines:
 {"ts":"<ISO>","worker":"<TASK-ID>","type":"<TYPE>","data":{...}}
 Types: code_pattern, integration_point, convention, blocker, key_finding, decision
 
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions.
+- Success path → result_status=completed after verification passes
+- Failure path → unrecoverable error (build fails, scope unclear, contract violation) → result_status=failed with error message
+- Blocked path → cannot proceed without upstream fix → result_status=blocked with error explaining what is needed
+- Timeout path → approaching max_runtime_seconds → revert partial unsafe work, report blocked with error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
 ## Output
-Return via output_schema:
-- result_status: completed | failed | blocked
+Return via output_schema (matches schema declared in spawn call):
+- id: your CSV row id (mandatory)
+- result_status: completed | failed | blocked (mandatory)
 - findings: key findings summary (max 500 chars, be specific and actionable)
-- files_modified: semicolon-separated paths of created/modified files
-- error: error message if result_status is not completed
+- files_modified: semicolon-separated paths of created/modified files (empty if none)
+- error: error message if result_status is not completed (empty otherwise)
+
+## Hard Constraints
+- Do NOT write to tasks.csv, wave-*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
 ```
 
 </actions>

package/.codex/skills/team-coordinate/specs/role-catalog.md

@@ -80,6 +80,26 @@ All agents — regardless of dynamically assigned role — MUST follow these tra
 - 2 retries exhausted → report `failed` with evidence
 - NEVER skip verification and report completed
 
+### Termination Contract (MANDATORY)
+
+Every spawned worker MUST call `report_agent_job_result` EXACTLY ONCE before exiting. NO exceptions:
+
+| Path | Action |
+|------|--------|
+| Success | `result_status=completed` after verification passes |
+| Failure | `result_status=failed` with error message (build error, file write failure, unrecoverable tool error) |
+| Blocked | `result_status=blocked` when upstream missing OR retries exhausted |
+| Timeout | Approaching `max_runtime_seconds` → revert partial unsafe work → `result_status=blocked` with error="timeout" |
+
+- NEVER continue indefinitely.
+- NEVER exit silently.
+- NEVER omit `report_agent_job_result`.
+
+### Hard Constraints
+
+- Do NOT write to `tasks.csv`, `wave-*.csv`, `results.csv` — orchestrator owns those.
+- Do NOT call `spawn_agents_on_csv` (no recursion).
+
 ## 6. Quality Scoring
 
 | Result | Score | Action |

package/.codex/skills/team-lifecycle-v4/SKILL.md

@@ -302,19 +302,23 @@ Extract wave N rows + add `prev_context` column.
 
 ```javascript
 spawn_agents_on_csv({
-  csv_path: `${sessionFolder}/wave-${N}.csv`,
+  csv_path: `${sessionFolder}/wave-${N}.csv`,    // only rows where wave==N AND status=="pending"
   id_column: "id",
   instruction: buildLifecycleInstruction(sessionFolder, skillRoot),
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
   output_schema: {
-    id,
-    result_status,    // completed | failed | blocked
-    findings,         // key findings (max 500 chars)
-    files_modified,   // semicolon-separated paths
-    quality_score,    // 0-100
-    error             // error message
+    type: "object",
+    properties: {
+      id:             { type: "string" },
+      result_status:  { type: "string", enum: ["completed", "failed", "blocked"] },
+      findings:       { type: "string", maxLength: 500 },
+      files_modified: { type: "string", description: "Semicolon-separated paths" },
+      quality_score:  { type: "string", description: "0-100" },
+      error:          { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
   }
 })
 ```
@@ -363,6 +367,18 @@ For roles with commands/ subdirectory, load the relevant command file based on y
 3. Retry on verification failure (max 2 retries)
 4. Report blocked if still failing after retries
 
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions.
+- Success → result_status=completed after all verifications pass
+- Failure → result_status=failed with error message (build error, file write fail)
+- Blocked → result_status=blocked when upstream missing OR after retries exhausted
+- Timeout → near max_runtime_seconds → revert partial unsafe work → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+## Hard Constraints
+- Do NOT write to tasks.csv, wave-*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
+
 ## Discovery Protocol
 Write task output to {sessionFolder}/discoveries/{task_id}.json:
 {

package/.codex/skills/team-lifecycle-v4/instructions/agent-instruction.md

@@ -811,6 +811,24 @@ All roles read/write `{session}/discoveries.ndjson`:
 
 ---
 
+## Termination Contract (MANDATORY for ALL roles)
+
+Every spawned worker — regardless of role — MUST call `report_agent_job_result` EXACTLY ONCE before exiting. NO exceptions:
+
+| Path | Action |
+|------|--------|
+| Success | `status=completed` after verification passes |
+| Failure | `status=failed` with error message (unrecoverable error) |
+| Blocked | `status=failed` (no separate "blocked" enum here — use error message to explain blockage) |
+| Timeout | Approaching `max_runtime_seconds` → revert partial unsafe work → `status=failed` with error="timeout" |
+
+Rules:
+- NEVER continue indefinitely.
+- NEVER exit silently.
+- NEVER omit `report_agent_job_result`.
+- Do NOT write to tasks.csv, wave-*.csv, results.csv — orchestrator owns those.
+- Do NOT call `spawn_agents_on_csv` (no recursion).
+
 ## Output Format
 
 All roles use `report_agent_job_result` with this schema:
@@ -825,3 +843,5 @@ All roles use `report_agent_job_result` with this schema:
   "error": ""
 }
 ```
+
+Note: spawn output_schema in SKILL.md uses `result_status` (not `status`). The orchestrator's merge step maps `result_status` → master `status`. Workers report via `report_agent_job_result` which the harness converts to the CSV result row — the field key here (`status`) is the worker-facing field name documented for this skill family.

package/.codex/skills/team-quality-assurance/SKILL.md

@@ -178,10 +178,48 @@ Session: {sessionFolder}
 Discovery board: {sessionFolder}/discoveries.ndjson
 Previous context: 'prev_context' column
 
-## Output
-result_status, findings, files_modified, coverage_score (QARUN only), error
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions.
+- Success → result_status=completed
+- Failure → result_status=failed with error message
+- Blocked → result_status=blocked when upstream missing
+- Timeout → near max_runtime_seconds → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+## Output (must match output_schema)
+{
+  "id": "<your CSV row id>",
+  "result_status": "completed" | "failed" | "blocked",
+  "findings": "<key findings, max 500 chars>",
+  "files_modified": "<semicolon-separated paths or empty>",
+  "coverage_score": "<0-100 or empty>" (QARUN only),
+  "error": "<message if not completed>"
+}
+
+## Hard Constraints
+- Do NOT write to tasks.csv, wave-*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
 ```
 
+### Spawn output_schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":             { "type": "string" },
+    "result_status":  { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":       { "type": "string", "maxLength": 500 },
+    "files_modified": { "type": "string" },
+    "coverage_score": { "type": "string" },
+    "error":          { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge maps `result_status` → master `status`.
+
 </actions>
 </state_machine>
 

package/.codex/skills/team-review/SKILL.md

@@ -172,10 +172,50 @@ Discovery board: {sessionFolder}/discoveries.ndjson
 Previous context: 'prev_context' column
 Dimensions: {skillRoot}/specs/dimensions.md
 
-## Output
-result_status, findings, files_modified, finding_count, verdict (REV only), error
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions.
+- Success → result_status=completed after scan/review/fix completes
+- Failure → result_status=failed with error message
+- Blocked → result_status=blocked when upstream missing
+- Timeout → near max_runtime_seconds → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+## Output (must match output_schema)
+{
+  "id": "<your CSV row id>",
+  "result_status": "completed" | "failed" | "blocked",
+  "findings": "<key findings, max 500 chars>",
+  "files_modified": "<semicolon-separated paths or empty>",
+  "finding_count": "<integer or empty>",
+  "verdict": "PASS" | "WARN" | "BLOCK" | "" (REV only),
+  "error": "<message if not completed>"
+}
+
+## Hard Constraints
+- Do NOT write to tasks.csv, wave-*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
 ```
 
+### Spawn output_schema
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":             { "type": "string" },
+    "result_status":  { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":       { "type": "string", "maxLength": 500 },
+    "files_modified": { "type": "string" },
+    "finding_count":  { "type": "string" },
+    "verdict":        { "type": "string", "enum": ["PASS", "WARN", "BLOCK", ""] },
+    "error":          { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge maps `result_status` → master `status`.
+
 </actions>
 </state_machine>
 

package/.codex/skills/team-tech-debt/SKILL.md

@@ -187,10 +187,53 @@ Session: {sessionFolder}
 Discovery board: {sessionFolder}/discoveries.ndjson
 Previous context: 'prev_context' column
 
-## Output
-result_status, findings, files_modified, debt_count, regression_detected (TDVAL), error
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting. NO exceptions.
+- Success → result_status=completed after verification
+- Failure → result_status=failed with error message
+- Blocked → cannot proceed without upstream fix → result_status=blocked
+- Timeout → near max_runtime_seconds → revert partial unsafe work → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+## Output (must match output_schema)
+Return JSON:
+{
+  "id": "<your CSV row id>",
+  "result_status": "completed" | "failed" | "blocked",
+  "findings": "<key findings, max 500 chars>",
+  "files_modified": "<semicolon-separated paths or empty>",
+  "debt_count": <integer or empty>,
+  "regression_detected": "true" | "false" | "" (TDVAL only),
+  "error": "<message if not completed>"
+}
+
+## Hard Constraints
+- Do NOT write to tasks.csv, wave-*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
 ```
 
+### Spawn output_schema
+
+When the coordinator dispatches a wave via `spawn_agents_on_csv`, it MUST use the strict JSON Schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":                  { "type": "string" },
+    "result_status":       { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":            { "type": "string", "maxLength": 500 },
+    "files_modified":      { "type": "string" },
+    "debt_count":          { "type": "string" },
+    "regression_detected": { "type": "string", "enum": ["true", "false", ""] },
+    "error":               { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge maps `result_status` → master `status`.
+
 </actions>
 </state_machine>