maestro-flow 0.4.16 → 0.4.18

package/.claude/commands/maestro.md

@@ -23,7 +23,7 @@ Entry points:
 - **`/maestro --dry-run "intent"`** — Show chain, no execution
 - **`/maestro --super "intent"`** — Production-ready mode (read maestro-super.md)
 
-Session: `.workflow/.maestro/{session_id}/status.json`
+**Session**: `.workflow/.maestro/{session_id}/status.json` — 工作流唯一真源。session_id 格式 `maestro-{YYYYMMDD-HHmmss}`（本 command 创建，静态链）或 `ralph-{YYYYMMDD-HHmmss}`（`/maestro-ralph` 创建，自适应链）。两类都由 `/maestro-ralph-execute` 推进；schema 与 ralph 共用（含 `ralph_protocol_version: "1"` + `active_step_index`）。
 </purpose>
 
 <deferred_reading>

package/.codex/skills/learn-decompose/SKILL.md

@@ -54,7 +54,7 @@ Resolve target to file list. Load coding specs: `maestro spec load --category co
 
 ### Phase 2: Wave 1 — Parallel Dimension Scans
 
-Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
+Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2). Initialize every row with `status="pending"`. Filter `wave==N AND status=="pending"` when writing each wave CSV.
 
 | id | dimension | focus |
 |----|-----------|-------|
@@ -64,7 +64,38 @@ Generate `tasks.csv` with 4 dimension rows (wave 1) + 1 cross-ref row (wave 2):
 | 4 | error | Boundaries, retry/backoff, fallbacks, guards, logging |
 | 5 | cross-ref | Dedup + catalog from wave 1 findings |
 
-Each dimension agent returns:
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "dimension":     { "type": "string", "enum": ["structural", "behavioral", "data", "error", "cross-ref"] },
+    "patterns":      { "type": "string", "description": "JSON array string: [{name, dimension, confidence, anchors, description, rationale, tradeoffs}]" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `dimension`, `patterns`, `findings`, `error`.
+
+**Shared termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed (patterns may be empty array if nothing found)
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=completed with partial patterns
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Every finding MUST include file:line anchors. No speculation.
+- Read-only analysis. Do NOT modify source.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+Each dimension agent populates `patterns` as a JSON array string of:
 ```json
 [{
   "name": "pattern name",
@@ -79,7 +110,7 @@ Each dimension agent returns:
 
 ### Phase 3: Wave 2 — Cross-Reference + Catalog
 
-Single agent receives all wave 1 findings via `prev_context`. Tasks:
+Single agent receives all wave 1 findings via `prev_context`. Uses same `output_schema` + termination contract above. Tasks:
 - Match against dedup set → mark as `documented`, `known`, or `new`
 - Merge duplicates across dimensions (same pattern found by multiple agents)
 - Flag contradictions with documented conventions

package/.codex/skills/learn-retro/SKILL.md

@@ -44,7 +44,7 @@ $ARGUMENTS — lens selection and scope flags.
 **3a: Collect decisions** from wiki, specs, git log, phase context, .workflow/specs/learnings.md.
 **3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
 
-**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
+**3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents; filter `wave==1 AND status=="pending"`):
 
 | id | perspective | focus |
 |----|------------|-------|
@@ -52,6 +52,36 @@ $ARGUMENTS — lens selection and scope flags.
 | 2 | cost | Complexity added, coupling, tech debt. Grade: low-cost/acceptable/expensive |
 | 3 | hindsight | Right call with current knowledge? Grade: confirmed/questionable/should-revisit |
 
+**output_schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "perspective":   { "type": "string", "enum": ["technical", "cost", "hindsight"] },
+    "grade":         { "type": "string" },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "grade", "findings"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `perspective`, `grade`, `findings`, `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 grade
+- Failure → result_status=failed with error message
+- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only analysis. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
+
 **3d: Classify lifecycle**: Validated / Aging / Questionable / Stale / Reversed.
 
 ### Phase 4: Unified Report

package/.codex/skills/learn-second-opinion/SKILL.md

@@ -47,12 +47,42 @@ Resolve target to content. Load specs, wiki search, prior lessons for context br
 | 3 | strategist | Scalability, extensibility, architecture alignment | coupling, cohesion |
 | 4 | synthesis | Merge verdicts → agreements, disagreements, top 3 recommendations | combined verdict |
 
-Wave 1: 3 persona agents in parallel. Wave 2: synthesis agent with wave 1 findings as prev_context.
-
-Each persona returns: `{ persona, verdict: approve|concern|reject, confidence, findings: [{severity, description, location, suggestion}], summary }`
+Wave 1: 3 persona agents in parallel (filter `wave==1 AND status=="pending"`). Wave 2: synthesis agent with wave 1 findings as prev_context.
+
+**output_schema** (both waves):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed"] },
+    "persona":       { "type": "string" },
+    "verdict":       { "type": "string", "enum": ["approve", "concern", "reject", ""] },
+    "confidence":    { "type": "string", "description": "0-100" },
+    "findings":      { "type": "string", "description": "JSON array of {severity, description, location, suggestion}, max 500 chars summary" },
+    "summary":       { "type": "string", "maxLength": 500 },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "summary"]
+}
+```
+
+Merge: `result_status` → master `status`; copy `persona`, `verdict`, `confidence`, `findings`, `summary`, `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
+- Timeout → near max_runtime_seconds → result_status=failed, error="timeout (partial)"
+- NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+- Read-only analysis. Do NOT modify source files.
+Do NOT write to tasks.csv, wave-*.csv, results.csv. Do NOT call spawn_agents_on_csv (no recursion).
+```
 
 #### Challenge Mode
-Single agent via spawn_agents_on_csv (1 worker). Adversarial analysis with forcing questions:
+Single agent via spawn_agents_on_csv (max_concurrency: 1) with the same `output_schema` + termination contract above. Adversarial analysis with forcing questions:
 - "What assumption would invalidate this entire approach?"
 - "What's the simplest thing that breaks this?"
 - "What's the implicit contract that isn't enforced?"

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

@@ -152,29 +152,63 @@ S_AGGREGATE:
 
 <actions>
 
+### Shared Spawn Contract (all three waves)
+
+Every `spawn_agents_on_csv` call in this skill MUST use the strict JSON Schema below and the shared termination contract.
+
+**Output Schema**:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "id":            { "type": "string" },
+    "result_status": { "type": "string", "enum": ["completed", "failed", "blocked"] },
+    "findings":      { "type": "string", "maxLength": 500 },
+    "score":         { "type": "string", "description": "0-100 (wave 2 scoring only)" },
+    "evidence":      { "type": "string", "description": "Code refs file:line (wave 1/2)" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+Merge step: `result_status` → master `status`; copy `findings`, `score`, `evidence`, `error`.
+
+**Termination contract** (embed in every instruction):
+```
+You MUST call report_agent_job_result EXACTLY ONCE before exiting.
+- Success → result_status=completed
+- Failure → result_status=failed with error message
+- Blocked → upstream missing → 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({ csv_path, max_concurrency })`.
+Filter `wave==1 AND status=="pending"` -> write wave-1.csv -> `spawn_agents_on_csv({ csv_path, id_column:"id", instruction: EXPLORATION_INSTRUCTION + SHARED_TERMINATION_CONTRACT, max_concurrency, max_runtime_seconds: 3600, output_csv_path, output_schema })`.
 
 **Exploration agent** (3-layer per dimension):
 1. Module Discovery (breadth): keyword search, relevant files, module boundaries
 2. Structure Tracing (depth): top 3-5 files, call chains 2-3 levels, data flow
 3. Code Anchor Extraction (detail): code snippet 20-50 lines with file:line per finding
 
-Share via discovery board. Merge results -> master tasks.csv.
+Share via discovery board. Merge results -> master tasks.csv (map `result_status` → master `status`).
 
 ### A_SPAWN_WAVE_2
 
-Filter wave==2 -> build prev_context from wave 1 findings -> write wave-2.csv -> spawn.
+Filter `wave==2 AND status=="pending"` -> build prev_context from wave 1 findings -> write wave-2.csv -> spawn with `SCORING_INSTRUCTION + SHARED_TERMINATION_CONTRACT`.
 
 **Scoring agent** (6 dimensions: feasibility, impact, risk, complexity, alignment, maintainability):
 Score 0-100 with specific evidence (code refs from exploration). Each score MUST reference exploration findings.
 
-Merge results -> master tasks.csv.
+Merge results -> master tasks.csv (map `result_status` → master `status`).
 
 ### A_SPAWN_WAVE_3
 
-Filter wave==3 -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn.
+Filter `wave==3 AND status=="pending"` -> build prev_context from wave 2 scores (or project context for quick mode) -> spawn with `SYNTHESIS_INSTRUCTION + SHARED_TERMINATION_CONTRACT`.
 
 **Synthesis agent**:
 - Full mode: analysis.md (executive summary, per-dimension scores, risk matrix, Go/No-Go), context.md (Locked/Free/Deferred decisions), context-package.json, conclusions.json (with `scope_verdict` + `implementation_scope[]`)
@@ -262,5 +296,10 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Upstream context loaded via `--from` when specified
 - [ ] discoveries.ndjson append-only throughout
 - [ ] Next step routed (plan for Go, brainstorm for No-Go, plan --gaps for Gaps)
+- [ ] Session sealed via finish-work (archive.json written, optional spec/knowhow extraction)
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR=OUTPUT_DIR, SESSION_TYPE=analyze, SESSION_ID={artifact_id}, LINKED_MILESTONE={target_milestone or null}
+</on_complete>
 </output>

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

@@ -120,4 +120,9 @@ P6 gate: Pass (>=80%) → Handoff | Review (60-79%) → Handoff w/caveats | Fail
 - [ ] Readiness gate: Pass (>=80%) or Review (>=60%) with documented caveats
 - [ ] Artifact registered in state.json (type=blueprint)
 - [ ] context-package.json generated for downstream consumption
+- [ ] On gate Pass/Review: session sealed via finish-work (archive.json + optional spec/knowhow extraction). On Fail: skip — session stays active, excluded from wiki search.
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={session_dir}, SESSION_TYPE=blueprint, SESSION_ID={session_id}, LINKED_MILESTONE=null
+</on_complete>

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

@@ -212,6 +212,47 @@ CONSTRAINTS:
 7. **DO NOT STOP**: Continuous until all waves complete; only pause at [CHECKPOINT] (skipped with -y).
 </invariants>
 
+<spawn_contract>
+
+All three waves invoke `spawn_agents_on_csv` with the same shape — only `instruction` (inflated from `<agent_prompt_template>`) and `max_concurrency` differ. The orchestrator MUST:
+
+1. Filter master tasks.csv to `wave==N AND status=="pending"` before writing `wave-{N}.csv`.
+2. Use the strict JSON Schema below for `output_schema`.
+3. Append the shared termination contract to every inflated `description`.
+4. Merge: map `result_status` → master `status`; copy `findings`, `output_path`, `error`.
+
+**output_schema** (all waves):
+
+```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": "Primary deliverable absolute path (W1: guidance-specification.md; W2: {role}/analysis.md; W3: review-findings.json)" },
+    "error":         { "type": "string" }
+  },
+  "required": ["id", "result_status", "findings"]
+}
+```
+
+**Shared termination contract** (append to every inflated W1/W2/W3 description):
+
+```
+TERMINATION CONTRACT (mandatory — NO worker may end without calling report_agent_job_result):
+  - Success path → all required files written AND verified via Glob → result_status=completed, output_path set
+  - Failure path → unrecoverable error (write fail, missing input file) → result_status=failed
+  - Blocked path → upstream missing (W2 cannot read guidance-spec; W3 cannot read analysis.md) → result_status=blocked
+  - Timeout path → near max_runtime_seconds → finalize current write if safe → otherwise report blocked with error="timeout"
+  - NEVER continue indefinitely. NEVER exit silently. NEVER omit the call.
+  - NEVER return analysis as chat text — files on disk are the ONLY valid deliverable.
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv.
+  - Do NOT call spawn_agents_on_csv (no recursion).
+```
+
+</spawn_contract>
+
 <state_machine>
 
 <states>
@@ -387,4 +428,9 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] context-package.json generated with per-item `ref` traceability
 - [ ] discoveries.ndjson append-only throughout
 - [ ] context.md aggregates session results with next-step routing
+- [ ] Session sealed via finish-work (auto mode only)
 </success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=brainstorm, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+</on_complete>

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

@@ -257,16 +257,72 @@ 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: buildExecutorInstruction(sessionFolder, phaseDir, autoCommit, specsContent),  // agent: ~/.codex/agents/workflow-executor.toml
-  max_concurrency: maxConcurrency, max_runtime_seconds: 3600,
+  instruction: EXECUTOR_INSTRUCTION,              // see "Executor Worker Contract" below
+  max_concurrency: maxConcurrency,
+  max_runtime_seconds: 3600,
   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" },
+      tests_passed:   { type: "string", enum: ["true", "false", "n/a"] },
+      error:          { type: "string" }
+    },
+    required: ["id", "result_status", "findings"]
+  }
 })
 ```
 
-4. Merge results into master `tasks.csv`: map `result_status` from `wave-{N}-results.csv` to the `status` column in master CSV. Delete `wave-{N}.csv` AND `wave-{N}-results.csv` after merge.
+4. Merge results into master `tasks.csv`: map `result_status` from `wave-{N}-results.csv` to the `status` column in master CSV; copy `findings`, `files_modified`, `tests_passed`, `error`. Delete `wave-{N}.csv` AND `wave-{N}-results.csv` after merge.
+
+#### Executor Worker Contract (EXECUTOR_INSTRUCTION)
+
+The literal `instruction` string passed to `spawn_agents_on_csv` MUST include the following contract (substitute `{sessionFolder}`, `{phaseDir}`, `{autoCommit}`, `{specsContent}` at build time):
+
+```
+You are a task executor. ONE task row is assigned to you.
+
+INPUT (from your CSV row):
+  - id, title, description, prev_context (findings from upstream tasks)
+  - meta.tdd_phase (red|green|refactor) if TDD mode is enabled
+
+REQUIRED STEPS:
+  1. Read prev_context — depend on upstream findings, not memory
+  2. Read shared discoveries: {sessionFolder}/discoveries.ndjson
+  3. Implement the task: edit/create files per description
+  4. Run verification — relevant tests; if TDD, honor tdd_phase semantics
+  5. If autoCommit and task succeeded → commit changes with task ID in message
+  6. Append discoveries (type=implementation_note / pattern) to 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 → all files written, tests pass → result_status=completed, tests_passed="true"
+  - Blocked path → cannot proceed (missing dep, unclear requirement, contract violation) → result_status=blocked with error explaining what is needed
+  - Failure path → unrecoverable error (build error, file write fail) → result_status=failed with error message
+  - Timeout path → approaching max_runtime_seconds → revert partial work, report blocked 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": "<one-sentence summary, max 500 chars>",
+    "files_modified": "<semicolon-separated paths or empty>",
+    "tests_passed": "true" | "false" | "n/a",
+    "error": "<message if not completed, else empty>"
+  }
+
+CONSTRAINTS:
+  - Modify ONLY files implicated by the task description and prev_context.
+  - Do NOT write to tasks.csv, wave-*.csv, results.csv, plan.json, or state.json — orchestrator owns those.
+  - Do NOT call spawn_agents_on_csv (no recursion).
+  - Honor specs loaded by orchestrator (passed via instruction context).
+```
 
 #### Blocked Task Handling
 

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>