maestro-flow 0.4.17 → 0.4.19

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

@@ -137,17 +137,17 @@ S_COMPLETE:
 
 1. **Checkpoint**: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: AskUserQuestion (Continue/Pause/Abort).
 
-2. **Skill nodes**: resolve runtime references → write wave-{N}.csv → spawn:
+2. **Skill nodes**: resolve runtime references → write wave-{N}.csv (only rows with status == "pending") → spawn:
 ```
 spawn_agents_on_csv({
   csv_path: "wave-{N}.csv", id_column: "id",
   instruction: SUB_AGENT_INSTRUCTION,
-  max_workers: waveSteps.length, max_runtime_seconds: 3600,
+  max_concurrency: waveSteps.length, max_runtime_seconds: 3600,
   output_csv_path: "wave-{N}-results.csv", output_schema: RESULT_SCHEMA
 })
 ```
 
-3. Read results → update step status/findings/artifacts
+3. Read results → map `result_status` → master step `status`; copy `summary` into findings and `artifacts` into the step artifact list
 4. **Barrier analysis**: read artifacts, update context per barrier table
 5. Append wave record to state.waves[], persist state.json
 
@@ -158,14 +158,33 @@ spawn_agents_on_csv({
 先原样执行技能调用：{skill_call}
 然后基于结果完成任务说明：{topic}
 限制：不要修改 .workflow/.maestro/ 下的 state 文件
-最后调用 report_agent_job_result，返回 JSON：
-{"status":"completed|failed","skill_call":"...","summary":"一句话","artifacts":"路径或空","error":"原因或空"}
+最后必须调用 report_agent_job_result（无论成功/失败/超时都必须上报）。
+
+TERMINATION CONTRACT（强制）：
+  - 成功：result_status = completed，summary 描述产出
+  - 失败：result_status = failed，error 写明原因
+  - 超时：临近 max_runtime_seconds 时立即上报 result_status = failed，error = "timeout"
+  - 禁止：无限循环、静默退出、跳过 report_agent_job_result
+
+OUTPUT（必须匹配 output_schema）：
+{"id":"<row id>","result_status":"completed|failed","skill_call":"...","summary":"一句话","artifacts":"路径或空","error":"原因或空"}
 ```
 
 ### RESULT_SCHEMA
 
 ```json
-{ "status": "completed|failed", "skill_call": "", "summary": "", "artifacts": "", "error": "" }
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "skill_call":    { "type": "string" },
+    "summary":       { "type": "string", "maxLength": 500 },
+    "artifacts":     { "type": "string" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "summary"]
+}
 ```
 
 </actions>

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

@@ -1,17 +1,22 @@
 ---
 name: maestro-ralph
 description: Use when the optimal command sequence is unclear and needs automated state-based determination
-argument-hint: "<intent> [-y] | status | continue"
+argument-hint: "<intent> [-y] | status [session-id] | continue [session-id]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 <purpose>
 Closed-loop decision engine for the maestro workflow lifecycle.
 Reads project state → infers position → builds adaptive chain → delegates execution.
 
-Entry points:
-- **`/maestro-ralph "intent"`** — New session: infer → decompose → build → emit /goal prompt（如有 decomposition）→ dispatch ralph-execute
-- **`/maestro-ralph continue`** — Wrapper; dispatches to ralph-execute（首选直接 `/maestro-ralph-execute` 推进 step）
-- **`/maestro-ralph status`** — Display session progress
+### Session
+
+`.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源（schema 见 `<appendix>`）。session_id 格式：`ralph-{YYYYMMDD-HHmmss}`（本 skill 创建，自适应链）或 `maestro-{YYYYMMDD-HHmmss}`（`/maestro` coordinator 创建，静态链）。两类都由 `/maestro-ralph-execute` 推进。session-id 省略时取最新 `status=="running"`。
+
+### Entry points
+
+- **`/maestro-ralph "intent"`** — 新建 session：infer → decompose → build → emit /goal prompt（如有 decomposition）→ dispatch ralph-execute
+- **`/maestro-ralph continue [session-id]`** — 恢复执行；省略=最新 running（首选直接 `/maestro-ralph-execute [session-id]`）
+- **`/maestro-ralph status [session-id]`** — 显示进度；省略=最新 ralph session
 
 > 推进规则：**step 推进由 `/maestro-ralph-execute` 负责**；ralph 仅在 build / decision 评估时介入。decision 节点由 ralph-execute 自动 `$maestro-ralph` 直调 handoff，无需用户手动切换。
 
@@ -48,9 +53,10 @@ $ARGUMENTS — intent text, flags, or keywords.
 
 **Parse:**
 ```
--y flag       → auto_confirm = true
-.md/.txt path → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
-Remaining     → intent
+-y flag                          → auto_confirm = true
+.md/.txt path                    → input_doc (supplementary context only, NEVER substitutes lifecycle stages)
+status|continue + session-id     → 当 intent ∈ {status,continue} 且后续 token 匹配 ralph-*|maestro-* → target_session_id
+Remaining                        → intent
 ```
 
 **State files:**
@@ -108,7 +114,8 @@ S_STATUS:
   → END             DO: A_SHOW_STATUS
 
 S_CONTINUE:
-  → S_DISPATCH      WHEN: running session found
+  → S_DISPATCH      WHEN: target_session_id provided AND session exists
+  → S_DISPATCH      WHEN: running session found (no target_session_id → latest running)
   → S_FALLBACK      WHEN: no running session               DO: display "无运行中的 ralph 会话"
 
 S_RESOLVE_PHASE:
@@ -189,7 +196,7 @@ S_FALLBACK:
 
 ### A_SHOW_STATUS
 
-1. Find latest ralph session (by created_at)
+1. 若 `target_session_id` 提供 → 直接加载 `.workflow/.maestro/{target_session_id}/status.json`；否则取最新 ralph session（by created_at）
 2. Display: Session, Status, Position, Progress, Current step
 3. List steps: [✓] completion_confirmed, [▸] current, [ ] pending, [◆] decision（`step.decision` 非空）；执行 step 附 `command_scope`(global/project) + `command_path`
 4. If `task_decomposition` present (absent → skip):

package/.codex/skills/maestro-ralph-execute/SKILL.md

@@ -9,7 +9,8 @@ Single-step executor for ralph (adaptive) and maestro (static) sessions.
 Each invocation: locate session → find next step → resolve args → execute → update → self-invoke next.
 
 Mutual invocation with `/maestro-ralph` forms a self-perpetuating work loop.
-Session: `.workflow/.maestro/*/status.json`
+
+**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `ralph-{YYYYMMDD-HHmmss}`（/maestro-ralph 创建，自适应链）或 `maestro-{YYYYMMDD-HHmmss}`（/maestro 创建，静态链）。两类都由本 skill 推进；省略 `[session-id]` 时取最新 `status=="running"`。Schema 详见 `/maestro-ralph` 的 Session Schema。
 </purpose>
 
 <context>

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

@@ -110,19 +110,50 @@ S_AGGREGATE:
 
 <actions>
 
+### Shared Spawn Contract (W1 and W2)
+
+Every `spawn_agents_on_csv` call MUST filter `wave==N AND status=="pending"` and use this strict JSON Schema:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "output_path":   { "type": "string", "description": "W2 only: absolute path of roadmap.md (empty for W1 agents that just return findings)" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `findings`, `output_path`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (W2: roadmap.md MUST exist on disk)
+- Failure → result_status=failed with error message
+- Blocked → upstream context insufficient → result_status=blocked
+- Timeout → near max_runtime_seconds → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 ### A_SPAWN_WAVE_1
 
-Filter wave==1 -> write wave-1.csv -> `spawn_agents_on_csv`.
+Filter `wave==1 AND status=="pending"` -> write wave-1.csv -> spawn.
 
-**Agents**: scope analysis (feature inventory + priority), risk analysis (unknowns + mitigations), dependency analysis (dependency graph + critical path).
+**Agents**: scope analysis (feature inventory + priority), risk analysis (unknowns + mitigations), dependency analysis (dependency graph + critical path). Read-only.
 
 Merge results -> master tasks.csv.
 
 ### A_SPAWN_WAVE_2
 
-Build prev_context from wave 1. Inject strategy + `--phases` constraint. Spawn.
+Filter `wave==2 AND status=="pending"`. Build prev_context from wave 1. Inject strategy + `--phases` constraint. Spawn.
 
-Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depends-on, requirements, success criteria), scope decisions.
+Assembly agent produces roadmap.md with Milestone > Phase hierarchy (goal, depends-on, requirements, success criteria), scope decisions. Verifies roadmap.md on disk before reporting completed.
 
 **Strategy selection** via uncertainty assessment (5 factors):
 | Factor | Low | Medium | High |

package/.codex/skills/maestro-ui-codify/SKILL.md

@@ -260,7 +260,35 @@ Write `tasks.csv` to `${sessionFolder}/tasks.csv`.
 
 ### Step 4: Wave Execution
 
-Execute waves sequentially via `spawn_agents_on_csv`.
+Execute waves sequentially via `spawn_agents_on_csv`. All four waves share the same `output_schema` shape (below) — only `instruction` differs.
+
+**Shared output_schema** (strict JSON Schema):
+
+```javascript
+const UI_CODIFY_OUTPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    id:            { type: "string" },
+    result_status: { type: "string", enum: ["completed", "failed"] },
+    findings:      { type: "string", maxLength: 500 },
+    output_path:   { type: "string", description: "Absolute path of the file/dir produced by this worker (empty if failed)" },
+    error:         { type: "string" }
+  },
+  required: ["id", "result_status", "findings"]
+}
+```
+
+**Shared termination contract** (embed in every `instruction` below):
+
+```
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success → result_status=completed, output_path set to the absolute path of the artifact you wrote
+  - Failure → unrecoverable error → result_status=failed, output_path=""
+  - Timeout → near max_runtime_seconds, finalize current write if safe → otherwise report failed with error="timeout"
+  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 #### Wave 1: File Discovery (Barrier)
 
@@ -270,15 +298,15 @@ Filter `wave == 1 && status == pending` from master CSV. Write `wave-1.csv`.
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-1.csv`,
   id_column: "id",
-  instruction: `You are scanning a source directory for design-relevant files. Read the 'description' column for full instructions. Use Glob to find files, Read to sample content. Write file inventory JSON to the specified path. Report findings as a concise summary.`,
+  instruction: `You are scanning a source directory for design-relevant files. Read the 'description' column for full instructions. Use Glob to find files, Read to sample content. Write file inventory JSON to the specified path. Report findings as a concise summary.\n\n${SHARED_TERMINATION_CONTRACT}`,
   max_concurrency: 1,
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: UI_CODIFY_OUTPUT_SCHEMA
 })
 ```
 
-Merge wave-1-results.csv into master `tasks.csv`: map `result_status` -> master `status` column, then delete `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`, `output_path`, `error`. Delete `wave-1.csv` and `wave-1-results.csv`.
 
 #### Wave 2: Parallel Extraction (3 agents)
 
@@ -288,11 +316,11 @@ Filter `wave == 2 && status == pending`. Build `prev_context` from wave 1 findin
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-2.csv`,
   id_column: "id",
-  instruction: `You are extracting design tokens from source code. Read the 'description' column for your specific extraction task. Use prev_context for file inventory from discovery phase. Read source files, extract tokens, write output JSON to the specified path.`,
+  instruction: `You are extracting design tokens from source code. Read the 'description' column for your specific extraction task. Use prev_context for file inventory from discovery phase. Read source files, extract tokens, write output JSON to the specified path.\n\n${SHARED_TERMINATION_CONTRACT}`,
   max_concurrency: 3,
   max_runtime_seconds: 3600,
   output_csv_path: `${sessionFolder}/wave-2-results.csv`,
-  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: UI_CODIFY_OUTPUT_SCHEMA
 })
 ```
 
@@ -308,11 +336,11 @@ Filter `wave == 3 && status == pending`. Build `prev_context` from wave 2 findin
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-3.csv`,
   id_column: "id",
-  instruction: `You are generating a reference design package. Read the 'description' column for full instructions. Copy token files, generate preview.html and preview.css. Report package contents in findings.`,
+  instruction: `You are generating a reference design package. Read the 'description' column for full instructions. Copy token files, generate preview.html and preview.css. Report package contents in findings.\n\n${SHARED_TERMINATION_CONTRACT}`,
   max_concurrency: 1,
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-3-results.csv`,
-  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: UI_CODIFY_OUTPUT_SCHEMA
 })
 ```
 
@@ -326,11 +354,11 @@ Filter `wave == 4 && status == pending`. Build `prev_context` from wave 3 findin
 spawn_agents_on_csv({
   csv_path: `${sessionFolder}/wave-4.csv`,
   id_column: "id",
-  instruction: `You are building knowledge assets from a design package. Read the 'description' column for full instructions. Build manifest, write knowhow files, create spec entries, refresh wiki index, cleanup temp files. Report asset counts in findings.`,
+  instruction: `You are building knowledge assets from a design package. Read the 'description' column for full instructions. Build manifest, write knowhow files, create spec entries, refresh wiki index, cleanup temp files. Report asset counts in findings.\n\n${SHARED_TERMINATION_CONTRACT}`,
   max_concurrency: 1,
   max_runtime_seconds: 1800,
   output_csv_path: `${sessionFolder}/wave-4-results.csv`,
-  output_schema: { id, result_status: ["completed"|"failed"], findings, output_path, error }
+  output_schema: UI_CODIFY_OUTPUT_SCHEMA
 })
 ```
 

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

@@ -128,23 +128,58 @@ S_AGGREGATE:
 
 <actions>
 
+### Shared Spawn Contract (W1, W2, W3)
+
+Every `spawn_agents_on_csv` call MUST filter `wave==N AND status=="pending"` from master tasks.csv and use the strict JSON Schema below.
+
+**output_schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "verdict":       { "type": "string", "description": "Per-agent verdict (e.g., VERIFIED/FAILED/UNCERTAIN, SUBSTANTIVE/STUB, WIRED/ORPHANED/NOT_WIRED, COVERED/PARTIAL/MISSING)" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "gaps_found":    { "type": "string", "description": "Semicolon-separated gaps with severity + fix direction" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings", "verdict"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `verdict`, `findings`, `gaps_found`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed with concrete verdict
+- Failure → result_status=failed with error message
+- Blocked → upstream missing (W2/W3 cannot proceed) → result_status=blocked
+- Timeout → near max_runtime_seconds → result_status=blocked, error="timeout"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only verification. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv, verification.json. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 ### A_SPAWN_WAVE_1
 
-Filter wave==1 -> write wave-1.csv -> spawn.
+Filter `wave==1 AND status=="pending"` -> write wave-1.csv -> spawn.
 
-**Truth check agent**: Identify supporting artifacts, check existence + substance + wiring indicators. Status: VERIFIED / FAILED / UNCERTAIN. Report gaps with severity + fix direction.
+**Truth check agent**: Identify supporting artifacts, check existence + substance + wiring indicators. verdict: VERIFIED / FAILED / UNCERTAIN. Report gaps with severity + fix direction.
 **Artifact existence agent**: Check file on disk. Missing = gap (severity=critical). Exists = note size + structure for wave 2.
 
 ### A_SPAWN_WAVE_2
 
-Filter wave==2, skip if existence failed for that artifact. Build prev_context from wave 1 -> spawn.
+Filter `wave==2 AND status=="pending"`, skip if existence failed for that artifact. Build prev_context from wave 1 -> spawn.
 
 **Substance agent**: <10 lines real logic or placeholder markers = STUB. Otherwise SUBSTANTIVE.
-**Wiring agent**: Grep for import + actual usage beyond imports. Status: WIRED / ORPHANED / NOT_WIRED.
+**Wiring agent**: Grep for import + actual usage beyond imports. verdict: WIRED / ORPHANED / NOT_WIRED.
 
 ### A_SPAWN_WAVE_3
 
-Filter wave==3. Mark skipped per --skip-antipattern / --skip-tests. Build prev_context from waves 1+2 -> spawn.
+Filter `wave==3 AND status=="pending"`. Mark skipped per --skip-antipattern / --skip-tests. Build prev_context from waves 1+2 -> spawn.
 
 **Anti-pattern agent**: Extract modified files from summaries. Scan for TODO/FIXME/XXX/HACK, placeholder, empty returns, disabled tests. Categorize: Blocker / Warning / Info.
 **Nyquist agent**: Detect test framework, map requirements to test files, classify COVERED / PARTIAL / MISSING. Run coverage if available.

package/.codex/skills/manage-codebase-rebuild/SKILL.md

@@ -210,17 +210,17 @@ 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: buildRebuildInstruction(sessionFolder, sourceDirs),  // agent: ~/.codex/agents/workflow-codebase-mapper.toml
+  instruction: REBUILD_INSTRUCTION,                // see "Rebuild 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"] },
-      result_findings: { type: "string" },
-      error: { type: "string" }
+      id:              { type: "string" },
+      result_status:   { type: "string", enum: ["completed", "failed"] },
+      result_findings: { type: "string", description: "For task 1-3: JSON payload to merge into doc-index.json. For task 4-5: list of files written" },
+      error:           { type: "string" }
     },
     required: ["id", "result_status", "result_findings"]
   }
@@ -229,6 +229,53 @@ spawn_agents_on_csv({
 
 Merge `wave-1-results.csv` into master `tasks.csv`: map `result_status` -> master `status`, `result_findings` -> master `findings`, copy `error` as-is. After merge, delete temporary files (`wave-1.csv` and `wave-1-results.csv`).
 
+#### Rebuild Worker Contract (REBUILD_INSTRUCTION)
+
+```
+You are a codebase doc generator for ONE task (Component Scanner / Feature Mapper / Requirement Linker / Tech Registry Writer / Feature Map Writer). Your contract depends on your task id — read description carefully.
+
+DUAL CONTRACT (per task id):
+  Tasks 1-3 (Scanner/Mapper/Linker) → RETURN data via result_findings (JSON payload). Do NOT write files.
+  Tasks 4-5 (Writers) → MUST WRITE files via the Write tool. Verify each via Glob. Return file count + absolute paths via result_findings.
+
+REQUIRED STEPS:
+  1. Scan codebase per description and focus_area
+  2. For tasks 1-3: assemble JSON payload matching the documented section schema (components / features / requirements)
+  3. For tasks 4-5: render markdown documents and write them to disk; verify every intended file exists via Glob; if any file missing → result_status=failed
+  4. Append discoveries to {sessionFolder}/discoveries.ndjson if reusable
+  5. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success → result_status=completed
+  - Failure → unrecoverable error / write verification fails → result_status=failed
+  - Timeout → near max_runtime_seconds, finish current write/scan if safe, then report failed with error="timeout (partial)"
+  - NEVER skip report_agent_job_result.
+
+CONTRACT VIOLATION GUARD:
+  - Tasks 4-5 returning markdown content in result_findings instead of writing files → MUST self-report failed (orchestrator cannot assemble docs from text).
+  - Tasks 1-3 writing files to .workflow/codebase/ → MUST self-report failed (orchestrator owns assembly).
+
+OUTPUT (must match output_schema):
+  Tasks 1-3:
+  {
+    "id": "<your row id>",
+    "result_status": "completed" | "failed",
+    "result_findings": "<JSON payload to merge into doc-index.json section>",
+    "error": "<message if failed, else empty>"
+  }
+  Tasks 4-5:
+  {
+    "id": "<your row id>",
+    "result_status": "completed" | "failed",
+    "result_findings": "<count + semicolon-separated absolute paths of files written>",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv, doc-index.json (orchestrator assembles in Phase 3).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 ### Phase 3: Results -> .workflow/codebase/
 
 **Objective**: Assemble doc-index.json from agent findings, validate, update state.

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)