maestro-flow 0.4.17 → 0.4.18

package/.codex/skills/maestro-milestone-audit/SKILL.md

@@ -28,9 +28,9 @@ $maestro-milestone-audit "M1"
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,scope,check_targets,deps,wave
-"integ-1","Interface & dependency chains","Verify shared interfaces are consistent across phases: re-exports match, dependency chains unbroken, no circular imports between phase outputs","cross-phase imports, shared types, re-exports","grep for shared type names across phase output dirs; verify export/import consistency","","1"
-"integ-2","Data contracts & API consistency","Verify request/response schemas match across phases: API signatures consistent, error codes aligned, no contract drift","request/response schemas, API signatures, error codes","diff API type definitions across phases; check error code enum consistency","","1"
+id,title,description,scope,check_targets,deps,wave,status,findings,gaps_found,severity,error
+"integ-1","Interface & dependency chains","Verify shared interfaces are consistent across phases: re-exports match, dependency chains unbroken, no circular imports between phase outputs","cross-phase imports, shared types, re-exports","grep for shared type names across phase output dirs; verify export/import consistency","","1","pending","","","",""
+"integ-2","Data contracts & API consistency","Verify request/response schemas match across phases: API signatures consistent, error codes aligned, no contract drift","request/response schemas, API signatures, error codes","diff API type definitions across phases; check error code enum consistency","","1","pending","","","",""
 ```
 
 **Columns**:
@@ -44,13 +44,13 @@ id,title,description,scope,check_targets,deps,wave
 | `check_targets` | Input | Specific verification commands/grep patterns |
 | `deps` | Input | Dependencies (empty — all wave 1) |
 | `wave` | Computed | Wave number (always 1 — single parallel wave) |
-| `result_status` | Output | `pass` / `fail` / `warning` |
-| `findings` | Output | Detailed findings per dimension (max 500 chars) |
-| `gaps_found` | Output | Semicolon-separated list of integration gaps |
-| `severity` | Output | `critical` / `warning` / `info` per gap |
-| `error` | Output | Error message if check failed |
+| `status` | Lifecycle | `pending` (initial) → `pass`/`fail`/`warning`/`failed` (set by merge step from worker's `result_status`) |
+| `findings` | Lifecycle | Detailed findings per dimension (max 500 chars; merged) |
+| `gaps_found` | Lifecycle | Semicolon-separated list of integration gaps (merged) |
+| `severity` | Lifecycle | `critical` / `warning` / `info` per gap (merged) |
+| `error` | Lifecycle | Error message if check failed (merged) |
 
-**Column separation rule**: Input columns and Output columns MUST NOT share names. Wave CSV only contains Input columns. Output columns are returned exclusively via output_schema.
+**Column separation rule**: Wave CSV (input to `spawn_agents_on_csv`) contains Input columns only. Workers return Output columns exclusively via `output_schema` using `result_status` (NOT `status`). Merge maps `result_status` → master `status`.
 
 ### Session Structure
 
@@ -95,16 +95,67 @@ Verify all adhoc-scoped artifacts completed. For each execute artifact, verify a
 
 ```javascript
 spawn_agents_on_csv({
-  csv_path: `${sessionFolder}/wave-1.csv`,
+  csv_path: `${sessionFolder}/wave-1.csv`,     // rows where wave==1 AND status=="pending"
   id_column: "id",
-  instruction: `You are an integration checker for milestone ${milestone}. For each row, examine the scope and check_targets. Search the codebase for inconsistencies, contract drift, and broken dependencies across phase outputs. Report findings with file:line references. Set result_status to pass/fail/warning. List specific gaps in gaps_found (semicolon-separated).`,
-  max_concurrency: 2, max_runtime_seconds: 600,
+  instruction: AUDIT_INTEGRATION_INSTRUCTION,   // see "Integration Checker Worker Contract" below
+  max_concurrency: 2,
+  max_runtime_seconds: 600,
   output_csv_path: `${sessionFolder}/wave-1-results.csv`,
-  output_schema: { id, result_status: [pass|fail|warning], findings, gaps_found, severity, error }
+  output_schema: {
+    type: "object",
+    properties: {
+      id:            { type: "string" },
+      result_status: { type: "string", enum: ["pass", "fail", "warning", "failed"] },
+      findings:      { type: "string", maxLength: 500 },
+      gaps_found:    { type: "string", description: "Semicolon-separated list of gaps" },
+      severity:      { type: "string", enum: ["critical", "warning", "info", ""] },
+      error:         { type: "string" }
+    },
+    required: ["id", "result_status", "findings", "severity"]
+  }
 })
 ```
 
 4. Merge results into master `tasks.csv`: map `result_status` → master `status` column, copy `findings`, `gaps_found`, `severity`, `error`. Delete temporary files (`wave-1.csv`, `wave-1-results.csv`) after merge.
+
+#### Integration Checker Worker Contract (AUDIT_INTEGRATION_INSTRUCTION)
+
+```
+You are an integration checker for milestone {milestone}. ONE integration dimension row is assigned to you.
+
+INPUT (from your CSV row):
+  - id (integ-N), title, description, scope, check_targets
+
+REQUIRED STEPS:
+  1. Examine scope and check_targets fields
+  2. Run check_targets — grep / read phase output dirs / diff API definitions
+  3. Identify inconsistencies, contract drift, broken dependencies across phase outputs
+  4. Record findings with file:line references for every gap
+  5. Call report_agent_job_result EXACTLY ONCE
+
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Pass path  → no gaps found → result_status=pass, severity="info"
+  - Warning path → minor gaps → result_status=warning, severity="warning"
+  - Fail path → critical contract drift or broken dependencies → result_status=fail, severity="critical"
+  - Failure path → cannot read scope, tool error → result_status=failed with error message
+  - Timeout path → near 600s, finalize current findings → report with what was collected
+  - NEVER skip report_agent_job_result.
+
+OUTPUT (must match output_schema):
+  {
+    "id": "<your row id>",
+    "result_status": "pass" | "warning" | "fail" | "failed",
+    "findings": "<one-sentence summary, max 500 chars>",
+    "gaps_found": "<semicolon-separated list of gaps, each with file:line; empty if pass>",
+    "severity": "critical" | "warning" | "info" | "",
+    "error": "<message if failed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Read-only inspection. Do NOT modify phase outputs.
+  - Do NOT write to tasks.csv, wave-*.csv, audit-report.md (orchestrator owns those).
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
 5. Parse `gaps_found` from all workers — aggregate into `.workflow/milestones/{milestone}/audit-report.md`
 6. Any worker with `result_status == fail` and `severity == critical` → milestone verdict = FAIL
 

package/.codex/skills/maestro-milestone-complete/SKILL.md

@@ -51,6 +51,18 @@ Copy each milestone artifact's directory to `.workflow/milestones/{milestone}/ar
 - If `artifact.path` is absolute, use as-is
 - Copy the entire resolved directory to `.workflow/milestones/{milestone}/artifacts/{artifact.name}/`
 
+**After each copy** (per archived session dir):
+
+a. If destination contains `archive.json` with `lifecycle.status == "sealed"`:
+   - Set `lifecycle.status = "archived"`, `lifecycle.archived_at = now`, `lifecycle.linked_milestone = {milestone}` (if null).
+
+b. If destination contains `context-package.json`, prune (scheme C — non-destructive):
+   - Compute `pruned` = { `open_questions` without answer/resolved_in; `constraints` status=open; `insights` beyond top 20; `references` whose path does not exist on disk }
+   - If any `pruned.*` non-empty: write `context-package.pruned.json` with the dropped items; rewrite `context-package.json` keeping only answered/resolved questions, locked constraints, `insights[0..20]`, valid-path references; update `archive.json.pruned = { at: now, counts, ref: "context-package.pruned.json" }`
+   - Otherwise: set `archive.json.pruned = { at: now, counts: zeros, ref: null }`
+
+c. If session dir lacks `archive.json` (legacy): skip a+b silently — legacy sessions are not indexed.
+
 Snapshot `roadmap.md` as `roadmap-snapshot.md` in the milestone archive.
 
 ### Step 3: Extract Learnings

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

@@ -154,8 +154,41 @@ S_REGISTER → END       DO: A_REGISTER
 
 <actions>
 
+### Shared Spawn Contract (W1 and W2)
+
+Every `spawn_agents_on_csv` call MUST filter `wave==N AND status=="pending"` rows from master tasks.csv, use the strict JSON Schema below, and embed the termination contract.
+
+**Output Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "files_modified":{ "type": "string", "description": "Semicolon-separated paths (W2 writes plan.json + .task/*)" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `findings`, `files_modified`, `error`.
+
+**Termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (W2: plan.json AND .task/* MUST exist on disk before reporting completed)
+- 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, state.json. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 ### Exploration agent responsibilities (W1)
-Each explores one angle: architecture (module boundaries, deps), patterns (similar implementations), tests (framework, conventions), risks (complexity, blockers). Reads files, maps dependencies, shares via discoveries.ndjson.
+Each explores one angle: architecture (module boundaries, deps), patterns (similar implementations), tests (framework, conventions), risks (complexity, blockers). Reads files, maps dependencies, shares via discoveries.ndjson. Read-only — does NOT write plan.json.
 
 ### Planning agent responsibilities (W2)
 Consumes all exploration findings + context.md + specs. Produces:
@@ -163,6 +196,8 @@ Consumes all exploration findings + context.md + specs. Produces:
 - `.task/TASK-*.json`: each with read_first[], convergence.criteria[] (grep-verifiable), concrete action/implementation
 - Deep Work Rules: every task has read_first with file being modified + source of truth files
 
+Verifies plan.json and every .task/*.json exists on disk before reporting completed; else report blocked.
+
 ### A_PLAN_CHECK
 Run plan-checker: coverage, dependency validity, criteria quality, pressure pass on highest-complexity task.
 Confidence: 5-dimension factor model + readiness gate.

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.