maestro-flow 0.4.17 → 0.4.18

package/.codex/skills/manage-issue-discover/SKILL.md

@@ -247,31 +247,63 @@ Initialize `discovery-state.json`:
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
-  instruction: buildDiscoverInstruction(sessionFolder, discoveryDir, mode),
+  instruction: DISCOVER_PERSPECTIVE_INSTRUCTION,   // see "Perspective Worker Contract" below
   max_concurrency: maxConcurrency,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { // required: id, result_status, findings
-    id: "string", result_status: "completed|failed",
-    findings: "string", issues_found: "string",
-    severity_distribution: "string", error: "string"
+  output_schema: {
+    type: "object",
+    properties: {
+      id:                    { type: "string" },
+      result_status:         { type: "string", enum: ["completed", "failed"] },
+      findings:              { type: "string", maxLength: 500 },
+      issues_found:          { type: "string", description: "JSON array string" },
+      severity_distribution: { type: "string", description: "JSON object string {critical, high, medium, low}" },
+      error:                 { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
   }
 })
 ```
 
-6. Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` -> master `status` column)
+6. Merge `wave-1-results.csv` into master `tasks.csv` (map `result_status` -> master `status` column; copy `findings`, `issues_found`, `severity_distribution`, `error`)
 7. Save per-perspective findings to `{discoveryDir}/{perspective}-findings.json`
 8. Update `discovery-state.json` with completed perspectives
 9. Delete temporary files: `wave-1.csv` and `wave-1-results.csv`
 
-**Perspective scan agent protocol**:
-- Scan all source files matching scope_glob
-- Identify concrete issues with file:line references
-- Rate each finding: critical / high / medium / low
-- Provide brief fix direction for each finding
-- Report affected_components[]
-- Share cross-cutting discoveries via discovery board
-- Output issues_found as JSON array + severity_distribution as JSON object
+#### Perspective Worker Contract (DISCOVER_PERSPECTIVE_INSTRUCTION)
+
+```
+You are a perspective scanner for ONE dimension. Your perspective, scope_glob, and description come from your CSV row.
+
+REQUIRED STEPS:
+  1. Read shared discoveries: {sessionFolder}/discoveries.ndjson (may be empty)
+  2. Scan all files matching scope_glob using Read/Grep/Glob (read-only)
+  3. For each finding: capture title, severity (critical|high|medium|low), description, file:line location, fix_direction, affected_components[]
+  4. Append cross-cutting patterns to discoveries.ndjson (dedup by type+key)
+  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 (issues_found may be empty array if nothing found)
+  - Timeout path → near max_runtime_seconds, STOP and report completed with partial issues_found (do NOT report failed for timeout — partial work is valuable)
+  - Failure path → unrecoverable error (cannot read scope, parse failure) → result_status=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": "<one-sentence summary, max 500 chars>",
+    "issues_found": "<JSON array string: [{\"title\":\"...\",\"severity\":\"...\",\"description\":\"...\",\"location\":\"file:line\",\"fix_direction\":\"...\",\"affected_components\":[...]}]>",
+    "severity_distribution": "<JSON object string: {\"critical\":N,\"high\":N,\"medium\":N,\"low\":N}>",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Every finding MUST have a concrete file:line reference. No speculative issues.
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv, or issues.jsonl (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 #### Wave 2: Dedup + Issue Creation (Single Agent)
 
@@ -285,10 +317,69 @@ spawn_agents_on_csv({
    ...
    ```
 5. Write `wave-2.csv` with `prev_context` column
-6. Execute `spawn_agents_on_csv` for dedup agent
+6. Execute:
+
+```javascript
+spawn_agents_on_csv({
+  csv_path: `${sessionFolder}/wave-2.csv`,
+  id_column: "id",
+  instruction: DEDUP_INSTRUCTION,            // see "Dedup Worker Contract" below
+  max_concurrency: 1,
+  max_runtime_seconds: 1800,
+  output_csv_path: `${sessionFolder}/wave-2-results.csv`,
+  output_schema: {
+    type: "object",
+    properties: {
+      id:                    { type: "string" },
+      result_status:         { type: "string", enum: ["completed", "failed"] },
+      findings:              { type: "string", maxLength: 500 },
+      issues_found:          { type: "string", description: "JSON array of deduplicated issues with ISS-* IDs" },
+      severity_distribution: { type: "string" },
+      error:                 { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
+  }
+})
+```
+
 7. Merge results into master `tasks.csv` (map `result_status` -> master `status` column)
 8. Delete temporary files: `wave-2.csv` and `wave-2-results.csv`
 
+#### Dedup Worker Contract (DEDUP_INSTRUCTION)
+
+```
+You are the dedup + issue creation worker. Your prev_context contains all wave-1 perspective findings.
+
+REQUIRED STEPS:
+  1. Parse prev_context — extract every issues_found JSON from upstream rows
+  2. Deduplicate: group by file path, compare descriptions (>80% overlap or same file:line → keep higher severity)
+  3. Assign collision-safe ID per unique issue: ISS-YYYYMMDD-NNN
+  4. Build full issue record (severity→priority: critical→1/high→2/medium→3/low→4; source="discover"; tags=[perspective])
+  5. Append deduplicated records to .workflow/issues/issues.jsonl AND {discoveryDir}/discovery-issues.jsonl
+  6. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory):
+  - Success → result_status=completed with issues_found = final deduped JSON array
+  - Timeout → near max_runtime_seconds, persist partial dedup, report completed with note in findings
+  - Failure → file write error, 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": "<pre-dedup count → post-dedup count summary>",
+    "issues_found": "<JSON array of final deduplicated issues>",
+    "severity_distribution": "<JSON object: {critical, high, medium, low}>",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Append-only writes to issues.jsonl. Never overwrite existing records.
+  - Every record MUST include source: "discover".
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 **Dedup agent protocol**:
 - Merge all perspective findings from prev_context into single list
 - Deduplicate: group by file path, compare descriptions (>80% overlap or same file:line → keep higher severity)

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`: