maestro-flow 0.4.17 → 0.4.19

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

@@ -141,6 +141,28 @@ For each layer L1->L3 (sequential, respecting --layer filter):
 6. Record per-scenario pass/fail
 7. Fail-fast: any critical-priority failed -> stop layer progression
 
+**Test Writer Spawn output_schema** (strict JSON Schema, used for both writer + diagnosis spawns):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":             { "type": "string" },
+    "result_status":  { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "red_result":     { "type": "string", "enum": ["expected_fail", "pass", "unexpected_fail", ""] },
+    "classification": { "type": "string", "enum": ["test_defect", "code_defect", "env_issue", ""] },
+    "fix_code":       { "type": "string" },
+    "evidence":       { "type": "string" },
+    "findings":       { "type": "string", "maxLength": 500 },
+    "files_modified": { "type": "string" },
+    "error":          { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `red_result` / `classification` / `fix_code` / `evidence` / `findings` / `files_modified` / `error`.
+
 **Test Writer Agent Instruction** (injected into spawn_agents_on_csv):
 ```
 You are a test writer. Write ONE test file for the given scenario.
@@ -154,16 +176,33 @@ You are a test writer. Write ONE test file for the given scenario.
 - Run test file once after writing
 
 ## RED-GREEN Rules
-- Test PASSES immediately: note "pass" — may need strengthening
-- Test FAILS as expected (tests real behavior): note "expected_fail" — good
-- Test FAILS unexpectedly (setup/import error): fix test setup, note "unexpected_fail"
+- Test PASSES immediately: red_result="pass" — may need strengthening
+- Test FAILS as expected (tests real behavior): red_result="expected_fail" — good
+- Test FAILS unexpectedly (setup/import error): fix test setup, red_result="unexpected_fail"
 - NEVER modify source code — only write/fix test files
 
-## Output
-- status: "written" if created, "failed" if unable
-- red_result: the RED phase outcome
-- findings: patterns discovered, notes for dependent scenarios (max 500 chars)
-- error: only if status == "failed"
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (test file written + run executed; red_result populated)
+- Failure → result_status=failed (cannot write test file, parse error, missing target)
+- Blocked → result_status=blocked (test framework unavailable)
+- Timeout → near max_runtime_seconds → result_status=failed with error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+## Output (must match output_schema)
+{
+  "id": "<row id>",
+  "result_status": "completed" | "failed" | "blocked",
+  "red_result": "expected_fail" | "pass" | "unexpected_fail" | "",
+  "findings": "<patterns discovered, notes for dependent scenarios, max 500 chars>",
+  "files_modified": "<test file path>",
+  "error": "<message if not completed, else empty>"
+}
+
+## Hard Constraints
+- Do NOT modify source code under test (only test files).
+- Do NOT write to scenarios.csv, layer-L*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
 
 ## Context
 - prev_context: {prev_context} (findings from prior layer)
@@ -181,7 +220,7 @@ OUTER LOOP (max_iter iterations):
       3. Diagnosis agent (see instruction below). test_defect -> provide fix. code_defect -> document evidence.
       4. Apply test_defect fixes, re-run layer
 
-**Diagnosis Agent Instruction** (injected into spawn_agents_on_csv):
+**Diagnosis Agent Instruction** (injected into spawn_agents_on_csv; uses same output_schema as Test Writer):
 ```
 You are a test failure diagnostician. Classify ONE test failure.
 
@@ -193,16 +232,31 @@ You are a test failure diagnostician. Classify ONE test failure.
   - code_defect: Source violates business rule (actual != expected requirement)
   - env_issue: Environment problem (service down, config missing, timeout)
 
-## Output
-- classification: test_defect / code_defect / env_issue
-- fix_code: If test_defect: "old_line → new_line" or full replacement. Empty for others.
-- evidence: file:line references supporting classification
-- error: only if cannot determine
-
-## Rules
+## Termination Contract (MANDATORY)
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed with concrete classification
+- Failure → result_status=failed if you cannot read test_file or target_file
+- Blocked → result_status=blocked when env_issue prevents diagnosis
+- Timeout → near max_runtime_seconds → result_status=failed with error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+
+## Output (must match output_schema)
+{
+  "id": "<row id>",
+  "result_status": "completed" | "failed" | "blocked",
+  "classification": "test_defect" | "code_defect" | "env_issue",
+  "fix_code": "<old_line → new_line or full replacement (test_defect only); empty otherwise>",
+  "evidence": "<file:line refs supporting classification>",
+  "findings": "<one-sentence diagnosis summary, max 500 chars>",
+  "error": "<message if not completed>"
+}
+
+## Hard Constraints
 - NEVER suggest source code changes — only test fixes for test_defect
 - Test correctly catching a real bug = code_defect, not test_defect
 - When uncertain: prefer code_defect (conservative)
+- Do NOT write to scenarios.csv, layer-L*.csv, results.csv (orchestrator owns those).
+- Do NOT call spawn_agents_on_csv (no recursion).
 ```
       5. If no test_defects remain: break inner
   REFLECT: analyze trends, log strategy, test confidence scoring (5 dims: scenario_coverage, test_quality, diagnostic_accuracy, strategy_effectiveness, infrastructure_fitness)

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

@@ -91,12 +91,12 @@ When `--yes` or `-y`: Auto-confirm hypothesis selection, skip interactive sympto
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,hypothesis,deps,context_from,wave
-"H1","Null pointer in login handler","Investigate whether login handler crashes due to null user object after failed DB lookup","User object is null when DB returns empty result; login.ts:42 dereferences without null check","","","1"
-"H2","Missing error boundary","Investigate whether unhandled promise rejection in auth middleware propagates to 500","Auth middleware catches DB errors but not validation errors; middleware.ts:78 has no catch block","","","1"
-"H3","Stale session token","Investigate whether expired session tokens bypass refresh logic","Session refresh only triggers on 403 but server returns 401 for expired tokens; session.ts:15","","","1"
-"FIX-H1","Fix null pointer in login","Apply null check before user object dereference in login handler","","H1","H1","2"
-"FIX-H3","Fix session token refresh","Update refresh trigger to also handle 401 status codes","","H3","H3","2"
+id,title,description,hypothesis,deps,context_from,wave,status,findings,evidence_for,evidence_against,fix_applied,verified,error
+"H1","Null pointer in login handler","Investigate whether login handler crashes due to null user object after failed DB lookup","User object is null when DB returns empty result; login.ts:42 dereferences without null check","","","1","pending","","","","","",""
+"H2","Missing error boundary","Investigate whether unhandled promise rejection in auth middleware propagates to 500","Auth middleware catches DB errors but not validation errors; middleware.ts:78 has no catch block","","","1","pending","","","","","",""
+"H3","Stale session token","Investigate whether expired session tokens bypass refresh logic","Session refresh only triggers on 403 but server returns 401 for expired tokens; session.ts:15","","","1","pending","","","","","",""
+"FIX-H1","Fix null pointer in login","Apply null check before user object dereference in login handler","","H1","H1","2","pending","","","","","",""
+"FIX-H3","Fix session token refresh","Update refresh trigger to also handle 401 status codes","","H3","H3","2","pending","","","","","",""
 ```
 
 **Columns**:
@@ -110,15 +110,17 @@ id,title,description,hypothesis,deps,context_from,wave
 | `deps` | Input | Semicolon-separated dependency task IDs (wave 2 depends on wave 1) |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
 | `wave` | Input | Wave number (1 = investigation, 2 = fix attempt) |
-| `result_status` | Output | `confirmed` / `refuted` / `inconclusive` / `fixed` / `fix_failed` / `failed` |
-| `findings` | Output | Key findings summary (max 500 chars) |
-| `evidence_for` | Output | Evidence supporting the hypothesis (wave 1) |
-| `evidence_against` | Output | Evidence refuting the hypothesis (wave 1) |
-| `fix_applied` | Output | Description of fix applied (wave 2 only) |
-| `verified` | Output | `true` / `false` -- whether fix was verified to work (wave 2 only) |
-| `error` | Output | Error message if failed |
+| `status` | Lifecycle | `pending` (initial) → `confirmed`/`refuted`/`inconclusive`/`fixed`/`fix_failed`/`failed`/`skipped` (set by merge step from worker's `result_status`) |
+| `findings` | Lifecycle | Key findings summary (max 500 chars; merged from worker output) |
+| `evidence_for` | Lifecycle | Evidence supporting the hypothesis (wave 1; merged) |
+| `evidence_against` | Lifecycle | Evidence refuting the hypothesis (wave 1; merged) |
+| `fix_applied` | Lifecycle | Description of fix applied (wave 2 only; merged) |
+| `verified` | Lifecycle | `true` / `false` — whether fix was verified to work (wave 2 only; merged) |
+| `error` | Lifecycle | Error message if failed (merged) |
 
-**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns + `prev_context`. Output columns are returned exclusively via `output_schema`.
+**Column separation rule**: Wave CSV (input to `spawn_agents_on_csv`) contains Input columns + `prev_context` only. Lifecycle columns are NEVER passed to workers. Workers return Output columns exclusively via `output_schema` — those output column names MUST NOT collide with Input column names. During merge: `result_status` → master `status`; other output columns copied as-is into matching lifecycle columns.
+
+**Initial state**: All rows are written with `status="pending"` and empty lifecycle columns. Each wave selects rows where `wave == N AND status == "pending"` from the master CSV.
 
 ### Per-Wave CSV (Temporary)
 
@@ -234,41 +236,150 @@ mkdir -p {sessionFolder}
 
 #### Wave 1: Hypothesis Investigation (Parallel)
 
-1. Extract wave 1 pending rows from master `tasks.csv` into `wave-1.csv` (no prev_context needed)
-2. Execute:
+1. **Extract wave-1 input**: filter master `tasks.csv` rows where `wave == 1 AND status == "pending"` → write `wave-1.csv` containing ONLY input columns (id, title, description, hypothesis, deps, context_from, wave). No lifecycle columns, no prev_context (wave 1 has no upstream).
+2. **Execute**:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
-  instruction: buildInvestigationInstruction(sessionFolder),  // agent: ~/.codex/agents/workflow-debugger.toml
-  max_concurrency: maxConcurrency, max_runtime_seconds: 3600,
+  instruction: WAVE1_INVESTIGATION_INSTRUCTION,  // see "Wave 1 Worker Contract" below
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { id, result_status: [confirmed|refuted|inconclusive|failed], findings, evidence_for, evidence_against, error }
+  output_schema: {
+    type: "object",
+    properties: {
+      id:               { type: "string" },
+      result_status:    { type: "string", enum: ["confirmed", "refuted", "inconclusive", "failed"] },
+      findings:         { type: "string", maxLength: 500 },
+      evidence_for:     { type: "string" },
+      evidence_against: { type: "string" },
+      error:            { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
+  }
 })
 ```
 
-3. Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` → master `status` column), delete `wave-1.csv` and `wave-1-results.csv`
-4. **Filter for wave 2**: Mark fix tasks as `skipped` if their hypothesis `result_status` was `refuted` or `inconclusive`
+3. **Merge**: for each row in `wave-1-results.csv`, look up master row by `id` and write `master.status = result_status`, then copy `findings`, `evidence_for`, `evidence_against`, `error`. Delete `wave-1.csv` and `wave-1-results.csv`.
+4. **Wave 2 gating** (read from MASTER `tasks.csv` after merge, NOT from wave-1-results.csv):
+   - For each `FIX-H{N}` row: read its `context_from` hypothesis ID (e.g., `H{N}`) from master; if master `H{N}.status != "confirmed"`, set `FIX-H{N}.status = "skipped"` (with findings = "upstream {H{N}.status}").
+   - Only rows where `status == "pending"` proceed to wave 2.
+
+#### Wave 1 Worker Contract (WAVE1_INVESTIGATION_INSTRUCTION)
+
+The literal `instruction` string passed to `spawn_agents_on_csv` MUST include the following contract (substitute `{sessionFolder}` at build time):
+
+```
+You are a hypothesis investigation worker. ONE hypothesis row from wave-1.csv is assigned to you.
+
+INPUT (from your CSV row):
+  - id, title, hypothesis, description
+
+REQUIRED STEPS:
+  1. Read shared discoveries: {sessionFolder}/discoveries.ndjson (may be empty)
+  2. Scan codebase for evidence using Read/Grep/Glob (read-only investigation)
+  3. Classify the hypothesis based on evidence collected:
+     - confirmed   → strong evidence supports the hypothesis (file:line proof)
+     - refuted     → strong evidence contradicts the hypothesis
+     - inconclusive → insufficient evidence within time budget; do NOT guess
+     - failed      → tool error / cannot read files / blocked by environment
+  4. Append discoveries to {sessionFolder}/discoveries.ndjson if reusable (root_cause / hypothesis_evidence types)
+  5. Call report_agent_job_result EXACTLY ONCE with the verdict
+
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success path  → result_status = confirmed | refuted, with evidence
+  - Timeout path  → if approaching {max_runtime_seconds}, STOP investigation and report inconclusive
+  - Failure path  → on any 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": "confirmed" | "refuted" | "inconclusive" | "failed",
+    "findings": "<one-sentence summary, max 500 chars>",
+    "evidence_for": "<bullet list of file:line refs supporting, or empty>",
+    "evidence_against": "<bullet list of file:line refs refuting, or empty>",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Do NOT modify source code. This is investigation only.
+  - Do NOT write to tasks.csv, wave-*.csv, or results.csv (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 #### Wave 2: Fix Attempts (Parallel, Confirmed Only)
 
-1. If no confirmed hypotheses remain, skip wave 2 entirely
-2. Extract wave 2 pending rows, build `prev_context` from confirmed wave 1 findings
-3. Write `wave-2.csv`, then execute:
+1. If no master rows have `wave == 2 AND status == "pending"` after gating, skip wave 2 entirely.
+2. **Extract wave-2 input**: filter master `tasks.csv` where `wave == 2 AND status == "pending"`. For each row, build `prev_context` by concatenating findings/evidence_for from each ID in `context_from` (read from master). Write `wave-2.csv` with input columns + `prev_context`.
+3. **Execute**:
 
 ```javascript
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-2.csv`,
   id_column: "id",
-  instruction: buildFixInstruction(sessionFolder),  // agent: ~/.codex/agents/workflow-debugger.toml
-  max_concurrency: maxConcurrency, max_runtime_seconds: 3600,
+  instruction: WAVE2_FIX_INSTRUCTION,  // see "Wave 2 Worker Contract" below
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: { id, result_status: [fixed|fix_failed|failed], findings, fix_applied, verified, error }
+  output_schema: {
+    type: "object",
+    properties: {
+      id:            { type: "string" },
+      result_status: { type: "string", enum: ["fixed", "fix_failed", "failed"] },
+      findings:      { type: "string", maxLength: 500 },
+      fix_applied:   { type: "string" },
+      verified:      { type: "string", enum: ["true", "false"] },
+      error:         { type: "string" }
+    },
+    required: ["id", "result_status", "findings", "verified"]
+  }
 })
 ```
 
-4. Merge `wave-2-results.csv` into master `tasks.csv` (map `result_status` → master `status` column), delete `wave-2.csv` and `wave-2-results.csv`
+4. **Merge**: write `master.status = result_status`, copy `findings`, `fix_applied`, `verified`, `error`. Delete `wave-2.csv` and `wave-2-results.csv`.
+
+#### Wave 2 Worker Contract (WAVE2_FIX_INSTRUCTION)
+
+```
+You are a fix worker. ONE confirmed hypothesis row is assigned to you.
+
+INPUT (from your CSV row):
+  - id (FIX-H{N}), title, description, prev_context (confirmed evidence from H{N})
+
+REQUIRED STEPS:
+  1. Read prev_context — the confirmed root cause evidence
+  2. Apply the minimal fix using Edit / Write
+  3. Run verification:
+     - If project has tests: run the relevant test suite via Bash
+     - If no tests: re-read the modified file and confirm the fix matches the planned change
+  4. Append discoveries (type=fix_applied) to {sessionFolder}/discoveries.ndjson if reusable
+  5. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory):
+  - Success path → fix applied AND verified → result_status=fixed, verified="true"
+  - Partial path → fix applied but verification failed → result_status=fix_failed, verified="false"
+  - Timeout path → approaching {max_runtime_seconds} with no fix applied → result_status=fix_failed with error="timeout"
+  - Failure path → cannot apply fix (file missing, parse error, etc.) → result_status=failed
+  - 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": "fixed" | "fix_failed" | "failed",
+    "findings": "<one-sentence summary of what was changed, max 500 chars>",
+    "fix_applied": "<file:line description of the change>",
+    "verified": "true" | "false",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Modify ONLY files implicated by prev_context evidence. No drive-by refactors.
+  - Do NOT write to tasks.csv, wave-*.csv, or results.csv.
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 ### Phase 3: Results Aggregation
 

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

@@ -169,24 +169,74 @@ For each wave N in ascending order:
 
 ```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: `You are a refactoring executor. For each task:
-1. Read files listed in read_first to understand context
-2. Apply refactoring described in description targeting scope files
-3. Verify convergence_criteria via grep (all criteria must pass)
-4. Run verification_cmd and report test result
-5. If tests fail: revert ALL changes for this task, set result_status=failed
-6. Append discoveries to ${sessionFolder}/discoveries.ndjson
-Report: files_modified (semicolon-separated), tests_passed (true/false), findings (what was changed and why)`,
-  max_concurrency: 1, max_runtime_seconds: 1800,
+  instruction: REFACTOR_INSTRUCTION,              // see "Refactor Worker Contract" below
+  max_concurrency: 1,
+  max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-${N}-results.csv`,
-  output_schema: { id, result_status: [completed|failed|blocked], findings, files_modified, tests_passed, error }
+  output_schema: {
+    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 (empty if reverted)" },
+      tests_passed:   { type: "string", enum: ["true", "false"] },
+      error:          { type: "string" }
+    },
+    required: ["id", "result_status", "findings", "tests_passed"]
+  }
 })
 ```
 
 4. Merge results into master `tasks.csv`: map `result_status` -> master `status` column, copy `findings`, `files_modified`, `tests_passed`, `error` into master. Delete temporary `wave-{N}.csv` and `wave-{N}-results.csv`.
 
+#### Refactor Worker Contract (REFACTOR_INSTRUCTION)
+
+```
+You are a refactoring executor. ONE task row is assigned to you.
+
+INPUT (from your CSV row):
+  - id, title, description (refactoring plan)
+  - read_first (semicolon-separated paths to read for context)
+  - scope (files in refactor scope)
+  - convergence_criteria (grep patterns that must pass after refactor)
+  - verification_cmd (test command to run)
+  - prev_context (findings from upstream tasks)
+
+REQUIRED STEPS:
+  1. Read all files in read_first to understand context
+  2. Apply refactoring per description, modifying only files in scope
+  3. Verify EVERY convergence_criterion via grep (ALL must pass; ANY miss → failure)
+  4. Run verification_cmd via Bash; capture pass/fail
+  5. If tests fail OR convergence fails → revert ALL changes for this task using git (or Edit reverse), set files_modified=""
+  6. Append discoveries (type=implementation_note / pattern) to {sessionFolder}/discoveries.ndjson
+  7. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success path → tests pass AND convergence passes → result_status=completed, tests_passed="true"
+  - Failed path → tests fail OR convergence fails → REVERT, result_status=failed, tests_passed="false"
+  - Blocked path → cannot apply (file missing, parse error, unclear scope) → result_status=blocked
+  - Timeout path → approaching max_runtime_seconds → REVERT partial changes, result_status=failed with error="timeout"
+  - 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" | "blocked",
+    "findings": "<what was changed and why, max 500 chars>",
+    "files_modified": "<semicolon-separated paths or empty if reverted>",
+    "tests_passed": "true" | "false",
+    "error": "<message if not completed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Modify ONLY files in scope. Never drive-by edit unrelated files.
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv, reflection-log.md (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 **5b. Reflect per wave:**
 
 Append to `reflection-log.md`:

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