maestro-flow 0.5.41 → 0.5.43

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

@@ -50,10 +50,11 @@ If `.workflow/issues/` does not exist, auto-create the directory and write an em
 ```
 Append JSON line to `issues.jsonl`.
 
-**list**: Read `issues.jsonl`, filter by `--status`, `--phase`, `--severity`, `--source`. Display as table:
+**list**: Read both `issues.jsonl` (active) and `issue-history.jsonl` (closed) to build the full issue set. Filter by `--status`, `--phase`, `--severity`, `--source`. When `--status closed` is specified, read from `issue-history.jsonl`. When no `--status` filter, merge both files. Display as table:
 ```
 ID              | Severity | Status | Title
 ISS-20260318-001 | high     | open   | Auth token expiry bug
+ISS-20260310-003 | medium   | closed | Stale cache entries
 ```
 
 **status**: Find issue by ID in `issues.jsonl`. Display all fields in detail format.
@@ -63,9 +64,12 @@ ISS-20260318-001 | high     | open   | Auth token expiry bug
 **close**: Find issue by ID, set status to `closed`, add `resolution` and `closed_at`. Move line from `issues.jsonl` to `issue-history.jsonl`.
 
 **link**: Bidirectional cross-reference between issue and task:
-1. Find issue by ID in `issues.jsonl`, add task ID to issue's `linked_tasks[]` array, rewrite the line
-2. Read task JSON at `.workflow/.task/{TASK-ID}.json` (or `.task/{TASK-ID}.json`). Edit the task's `linked_issues` field — append the issue ID to the array. If `linked_issues` field does not exist, create it as `[ISS-ID]`
-3. Both writes must succeed for the link to be considered complete
+1. **Pre-validate**: Verify issue ID exists in `issues.jsonl` AND task file exists at `.workflow/.task/{TASK-ID}.json` (or `.task/{TASK-ID}.json`). If either is missing, abort with error before any writes
+2. **Save rollback state**: Read and store the original issue line from `issues.jsonl` before modification
+3. **First write**: Find issue by ID in `issues.jsonl`, add task ID to issue's `linked_tasks[]` array, rewrite the line
+4. **Second write**: Read task JSON. Edit the task's `linked_issues` field — append the issue ID to the array. If `linked_issues` field does not exist, create it as `[ISS-ID]`
+5. **Rollback on failure**: If the second write (task file) fails, restore the original issue line in `issues.jsonl` from the saved rollback state and report the error
+6. Both writes must succeed for the link to be considered complete
 </execution>
 
 <error_codes>

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

@@ -78,16 +78,16 @@ When `--yes` or `-y`: Auto-confirm perspective selection, skip interactive valid
 ### tasks.csv (Master State)
 
 ```csv
-id,title,description,perspective,scope_glob,deps,context_from,wave
-"1","Security Scan","Scan codebase for security vulnerabilities: authentication bypass, injection flaws, XSS, CSRF, sensitive data exposure, insecure crypto, secrets in code. Rate each finding critical/high/medium/low with file:line references.","security","src/**/*.{ts,tsx,js,jsx}","","","1"
-"2","Performance Scan","Scan codebase for performance issues: N+1 queries, unbounded loops, missing caching, memory leaks, large payloads, blocking operations, unoptimized algorithms.","performance","src/**/*.{ts,tsx,js,jsx}","","","1"
-"3","Reliability Scan","Scan codebase for reliability issues: unhandled errors, missing retry logic, race conditions, data integrity gaps, missing graceful degradation, silent failures.","reliability","src/**/*.{ts,tsx,js,jsx}","","","1"
-"4","Maintainability Scan","Scan codebase for maintainability issues: code duplication, tight coupling, missing abstractions, unclear naming, dead code, overly complex functions.","maintainability","src/**/*.{ts,tsx,js,jsx}","","","1"
-"5","Scalability Scan","Scan codebase for scalability issues: hardcoded limits, single-threaded bottlenecks, stateful assumptions, schema rigidity, missing pagination.","scalability","src/**/*.{ts,tsx,js,jsx}","","","1"
-"6","UX Scan","Scan codebase for UX issues: confusing flows, missing user feedback, inconsistent behavior, missing loading states, poor error messages.","ux","src/**/*.{ts,tsx,js,jsx}","","","1"
-"7","Accessibility Scan","Scan codebase for accessibility issues: missing ARIA labels, keyboard navigation gaps, color contrast problems, missing alt text, focus management issues.","accessibility","src/**/*.{ts,tsx,js,jsx}","","","1"
-"8","Compliance Scan","Scan codebase for compliance issues: logging gaps, missing audit trails, data retention violations, privacy control gaps, regulatory requirement gaps.","compliance","src/**/*.{ts,tsx,js,jsx}","","","1"
-"9","Dedup + Issue Creation","Aggregate all perspective findings. Deduplicate by file path + description similarity (keep higher severity). Generate ISS-YYYYMMDD-NNN issue records. Append to .workflow/issues/issues.jsonl.","dedup","","1;2;3;4;5;6;7;8","1;2;3;4;5;6;7;8","2"
+id,title,description,perspective,scope_glob,deps,context_from,wave,status
+"1","Security Scan","Scan codebase for security vulnerabilities: authentication bypass, injection flaws, XSS, CSRF, sensitive data exposure, insecure crypto, secrets in code. Rate each finding critical/high/medium/low with file:line references.","security","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"2","Performance Scan","Scan codebase for performance issues: N+1 queries, unbounded loops, missing caching, memory leaks, large payloads, blocking operations, unoptimized algorithms.","performance","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"3","Reliability Scan","Scan codebase for reliability issues: unhandled errors, missing retry logic, race conditions, data integrity gaps, missing graceful degradation, silent failures.","reliability","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"4","Maintainability Scan","Scan codebase for maintainability issues: code duplication, tight coupling, missing abstractions, unclear naming, dead code, overly complex functions.","maintainability","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"5","Scalability Scan","Scan codebase for scalability issues: hardcoded limits, single-threaded bottlenecks, stateful assumptions, schema rigidity, missing pagination.","scalability","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"6","UX Scan","Scan codebase for UX issues: confusing flows, missing user feedback, inconsistent behavior, missing loading states, poor error messages.","ux","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"7","Accessibility Scan","Scan codebase for accessibility issues: missing ARIA labels, keyboard navigation gaps, color contrast problems, missing alt text, focus management issues.","accessibility","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"8","Compliance Scan","Scan codebase for compliance issues: logging gaps, missing audit trails, data retention violations, privacy control gaps, regulatory requirement gaps.","compliance","src/**/*.{ts,tsx,js,jsx}","","","1","pending"
+"9","Dedup + Issue Creation","Aggregate all perspective findings. Deduplicate by file path + description similarity (keep higher severity). Generate ISS-YYYYMMDD-NNN issue records. Append to .workflow/issues/issues.jsonl.","dedup","","1;2;3;4;5;6;7;8","1;2;3;4;5;6;7;8","2","pending"
 ```
 
 **Columns**:
@@ -102,6 +102,7 @@ id,title,description,perspective,scope_glob,deps,context_from,wave
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
 | `wave` | Computed | Wave number (1 = perspective scans, 2 = dedup + issue creation) |
+| `status` | Lifecycle | Task lifecycle status, initialized to `pending`. Updated to `completed`/`failed`/`skipped` after wave merge via `result_status` mapping |
 | `result_status` | Output | `completed` / `failed` / `skipped` (mapped to master `status` on merge) |
 | `findings` | Output | Key scan findings summary (max 500 chars) |
 | `issues_found` | Output | JSON array of discovered issues: `[{"title":"...","severity":"critical","description":"...","location":"file:line","fix_direction":"...","affected_components":["..."]}]` |
@@ -309,8 +310,8 @@ CONSTRAINTS:
 
 1. Read master `tasks.csv`
 2. Filter rows where `wave == 2` AND `status == pending`
-3. Check deps -- if all wave 1 agents failed, skip dedup
-4. Build `prev_context` from wave 1 findings:
+3. Check deps -- if all wave 1 agents failed, skip dedup (invariant 6)
+4. Build `prev_context` from **completed** wave 1 rows only. Exclude `failed`/`skipped` rows. For excluded rows, inject `[GAP: {perspective} scan failed — findings incomplete]` note. Set `evidence_incomplete: true` if any perspective failed:
    ```
    [Task 1: Security Scan] Found 3 issues: SQL injection in query builder (critical), missing CSRF token (high)...
    [Task 2: Performance Scan] Found 5 issues: N+1 query in user listing (high), missing pagination (medium)...
@@ -384,7 +385,7 @@ CONSTRAINTS:
 - 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)
 - For each unique finding: generate `ISS-YYYYMMDD-NNN` ID (collision-safe), build full issue record
-  - Severity-to-priority: critical→1, high→2, medium→3, low→4; source = "discovery", tags = ["{perspective}"]
+  - Severity-to-priority: critical→1, high→2, medium→3, low→4; source = "discover", tags = ["{perspective}"]
 - Append to `.workflow/issues/issues.jsonl` and `{discoveryDir}/discovery-issues.jsonl`
 - Report: pre-dedup count, post-dedup count, severity_distribution
 
@@ -503,7 +504,7 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"vulnerability","data":{"location":"s
 | `by-prompt` with empty prompt | Interactive prompt with suggested options |
 | Perspective agent timeout | Mark as failed, continue remaining perspectives |
 | All perspective agents failed | Skip dedup, report no findings |
-| Dedup agent failed | Use wave 1 results directly, create issues from raw findings |
+| Dedup agent failed | Do NOT write to issues.jsonl — preserve raw findings in context.md and `{discoveryDir}/` for manual review or retry. Mark session `incomplete`. |
 | issues.jsonl write failure | Retry once, then report error with findings in context.md |
 | CSV parse error | Validate format, show line number |
 | discoveries.ndjson corrupt | Ignore malformed lines |

package/.codex/skills/manage-knowhow/SKILL.md

@@ -30,7 +30,8 @@ $manage-knowhow "prune --before 2026-01-01 --type tip --dry-run"
 - `--type <session|tip|template|recipe|reference|decision>` — Filter by knowhow type
 - `--confirm` — Skip delete confirmation prompt
 - `--before <date>` / `--after <date>` — Date filters for prune
-- `--dry-run` — Preview prune without deleting
+- `--dry-run` — Preview prune without deleting (default for prune — use `--execute` to actually delete)
+- `--execute` — Required to actually perform prune deletions (prune defaults to dry-run)
 </context>
 
 <execution>
@@ -60,7 +61,7 @@ Default to `list` if no arguments. Parse first token as subcommand.
 
 **delete `<id|file>`**: Require confirmation (or `--confirm` flag). MEMORY.md cannot be deleted (E004). Remove entry file (WikiIndexer auto-updates `.workflow/wiki-index.json` on next access).
 
-**prune**: Requires at least one filter (`--tag`, `--type`, `--before`, `--after`). Workflow store only. `--dry-run` previews without deleting.
+**prune**: Requires at least one filter (`--tag`, `--type`, `--before`, `--after`). Workflow store only. Prune defaults to dry-run (preview only) — always display the list of entries that would be deleted first. To actually delete, user must pass `--execute`. When `--execute` is used, prompt for confirmation via `request_user_input` before proceeding (unless `--confirm` is also passed).
 
 ### Step 4: Integrity Check
 

package/.codex/skills/manage-knowhow-capture/SKILL.md

@@ -70,7 +70,7 @@ Prompt for or extract: language (`--lang`), usage context, code content, paramet
 Prompt for or extract: goal, prerequisites, numbered steps, expected outcome, common pitfalls, related entries. Sections: Goal, Prerequisites, Steps, Expected Outcome, Common Pitfalls, Related.
 
 **reference** (REF-{YYYYMMDD}-{slug}.md):
-Source from `--source` flag (offer WebFetch if URL). Extract: key points, applicable scenarios, quick examples. Sections: Source, Key Points, Applicable Scenarios, Quick Examples.
+Source from `--source` flag (fetch URL content via `Bash` curl if provided). Extract: key points, applicable scenarios, quick examples. Sections: Source, Key Points, Applicable Scenarios, Quick Examples.
 
 **decision** (DCS-{YYYYMMDD}-{slug}.md):
 Prompt for or extract: context, decision, alternatives (at least 2), rationale, consequences. Sections: Context, Decision, Alternatives Considered (table), Rationale, Consequences, Related.
@@ -105,11 +105,12 @@ Write to `.workflow/knowhow/{PREFIX}-{YYYYMMDD}-{slug}.md` with YAML frontmatter
 title: {auto or --title}
 description: {one-line summary for search results}
 type: {type}
-category: {type}
 created: {ISO timestamp}
 tags: [{tags}]
 ```
-Plus type-specific: `lang` (template), `source` (reference), `status` (decision), `assetType` + `codePaths` (asset), `codePaths` (blueprint). `category` written when `--category` provided. `description` always written — from `--description` flag or auto-generated from content.
+Plus type-specific: `lang` (template), `source` (reference), `status` (decision), `assetType` + `codePaths` (asset), `codePaths` (blueprint). `description` always written — from `--description` flag or auto-generated from content.
+
+**`category` field**: Only written to frontmatter when `--category` is explicitly provided (e.g. `--category coding`). Do NOT default `category` to the `type` value — `type` and `category` are distinct concepts: `type` is the knowhow content type (template, recipe, tip, etc.), `category` is the spec discovery category (coding, arch, test, debug, review, learning) used for agent injection routing.
 
 ### Step 6: Confirm
 

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

@@ -2,7 +2,7 @@
 name: manage-learn
 description: Capture and search learning insights and tips
 argument-hint: "[\"<insight text>\"|list|search <query>|show <INS-id>] [--category pattern|antipattern|decision|tool|gotcha|technique] [--tag t1,t2] [--phase N] [--confidence high|medium|low]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -48,7 +48,7 @@ $manage-learn "\"Zod v4 breaks z.object().strict() API\" --category gotcha --tag
 
 <invariants>
 1. **No LLM or CLI calls**: This skill is pure file I/O — parse, infer, append, confirm. No `shell_exec`, no `spawn_agent`.
-2. **Bootstrap on demand**: Create `.workflow/knowhow/` structure on first use; do not require it to exist.
+2. **Bootstrap on demand**: Create `.workflow/specs/` directory and `learnings.md` on first use; do not require it to exist.
 3. **Append-only learnings.md**: Never rewrite or delete existing entries.
 4. **Stable INS-ids**: `INS-{8hex}` from `hash(insightText + timestamp)` — same text at different times gets different ids.
 5. **Source field**: Always `"manual"` for captures from this skill; `"retrospective"` is reserved for `quality-retrospective`.

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

@@ -6,6 +6,10 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 ---
 <base>@~/.maestro/workflows/odyssey-base-codex.md</base>
 
+<required_reading>
+Required reading: base (`odyssey-base-codex.md`) before any actions. Load and apply base invariants, execution discipline, and shared actions before proceeding.
+</required_reading>
+
 <purpose>
 archaeology → explore → diagnose → fix & confirm → generalize → discover siblings → persist.
 Exhaustive iteration until root cause confirmed or INCONCLUSIVE.
@@ -158,7 +162,7 @@ S_RECORD   → END            : complete
 1. Parse arguments, generate slug, create SESSION_DIR
 2. `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + Grep keywords
 3. Derive `phase_goals[]` from flags
-4. Write `session.json` + `understanding.md` §1, emit Goal Prompt
+4. Write `session.json` + `understanding.md` §1, call `create_goal` with phase_goals as success_criteria
 
 Commit: `"odyssey-debug({slug}): INTAKE — parse target and load context"`
 
@@ -184,7 +188,7 @@ spawn_agents_on_csv({ csv_path:"tasks.csv", id_column:"id",
 
 Merge results → evidence.ndjson (phase: "archaeology").
 
-**Step 2 — CLI change review** via `maestro delegate --role analyze --mode analysis` (`run_in_background: true`):
+**Step 2 — CLI change review** via `maestro delegate --to claude --mode analysis` (`run_in_background: true`):
 - PURPOSE: Review recent modifications related to {issue}
 - EXPECTED: JSON [{commit_sha, risk_level, analysis, could_cause_issue, explanation}]
 
@@ -193,7 +197,7 @@ Update §2. Commit: `"odyssey-debug({slug}): ARCHAEOLOGY — git history analysi
 ### A_EXPLORE
 Skip if no CLI tools (W006).
 
-`maestro delegate --role explore --mode analysis` (`run_in_background: true`):
+`maestro delegate --to claude --mode analysis` (`run_in_background: true`):
 - PURPOSE: Call chains, recent changes, error gaps, similar patterns
 - EXPECTED: JSON {call_chains, recent_changes, error_gaps, similar_patterns}
 
@@ -208,7 +212,7 @@ Write `explore.json` + evidence phase=explore. Update §3. Mark G2. Commit: `"od
 Commit: `"odyssey-debug({slug}): DIAGNOSE — root cause confirmed"`
 
 ### A_ESCALATE_DIAGNOSIS
-`diagnosis_retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → INCONCLUSIVE → S_RECORD.
+`diagnosis_retries++`. < 3: `maestro delegate --to claude --mode analysis`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → INCONCLUSIVE → S_RECORD.
 
 ### A_FIX
 1. Present root cause + proposed fix. Normal: request_user_input | `-y`: auto proceed
@@ -218,7 +222,7 @@ Commit: `"odyssey-debug({slug}): FIX — {summary}"`
 
 ### A_CONFIRM
 1. Run covering tests
-2. `maestro delegate --role review --mode analysis` (`run_in_background: true`):
+2. `maestro delegate --to claude --mode analysis` (`run_in_background: true`):
    - EXPECTED: JSON {verdict, findings [{severity, description, suggestion}], regression_risk}
 3. `session.json.confirmation`: `{test_result, cli_review, overall: "confirmed|needs_rework"}`
 4. Update §6. `needs_rework` → S_FIX. `confirmed` → mark G3.
@@ -251,7 +255,7 @@ Update §7. Mark G4. Commit: `"odyssey-debug({slug}): GENERALIZE — pattern sca
 ### A_DISCOVER, A_RECORD
 Base shared_actions. Debug overrides:
 - **A_DISCOVER** routes scan hits per csv_schema wave results. Commit: `"odyssey-debug({slug}): DISCOVER — triage complete"`
-- **A_RECORD** learnings per Knowledge Persistence table
+- **A_RECORD** learnings per Knowledge Persistence table. **Confirmation gate**: Before writing spec entries, present proposed entries to user via `request_user_input` for confirmation. Skip confirmation only if `-y` flag is set.
 
 **Completion summary:**
 ```
@@ -281,7 +285,7 @@ Goals:      {done}/{total} ({skipped} skipped)
 | A_ESCALATE 3-strike | request_user_input | INCONCLUSIVE |
 | A_FIX direction | request_user_input | auto proceed |
 
-### Goal Prompt convergence rules
+### Goal convergence rules
 
 ```
 Stop when root cause confirmed (or INCONCLUSIVE), fix verified,
@@ -318,6 +322,7 @@ All sibling bugs fixed or issued — no leftovers.
 </success_criteria>
 
 <next_step_routing>
+<!-- suggest-only — do NOT auto-execute. Present these as suggestions to the user. -->
 | Condition | Next |
 |-----------|------|
 | Discovery issues | `/manage-issue list --source debug-odyssey` |

package/.codex/skills/odyssey-improve/SKILL.md

@@ -6,6 +6,10 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 ---
 <base>@~/.maestro/workflows/odyssey-base-codex.md</base>
 
+<required_reading>
+Required reading: base (`odyssey-base-codex.md`) before any actions. Load and apply base invariants, execution discipline, and shared actions before proceeding.
+</required_reading>
+
 <purpose>
 survey → 6-dimension audit → diagnose → fix → verify → generalize → discover → persist.
 Baseline-first, exhaustive iteration until zero remaining actionable findings.
@@ -172,7 +176,7 @@ S_RECORD   → END          : complete
 3. `maestro search "<keywords>"` + Glob prior sessions + ARCHITECTURE.md + spec load coding/debug
 4. **Baseline capture**: Record current metrics (test pass rate, bundle size, dependency count, complexity hotspots) to `session.json.baseline_metrics`
 5. Derive `phase_goals[]` from flags
-6. Write `session.json` + `understanding.md` section 1, emit Goal Prompt
+6. Write `session.json` + `understanding.md` section 1, call `create_goal` with phase_goals as success_criteria
 
 Commit: `"odyssey-improve({slug}): INTAKE — target parsed and baseline captured"`
 
@@ -217,13 +221,13 @@ Root cause analysis for critical/high findings.
 
 1. Group by dimension, prioritize by severity. For each: hypothesis → trace code path + git history → evidence (phase: "diagnosis")
 2. Ambiguity → evidence (phase: "decision"); Normal: request_user_input | `-y`: defer
-3. Complex findings: `maestro delegate --role analyze --mode analysis` (`run_in_background: true`)
+3. Complex findings: `maestro delegate --to claude --mode analysis` (`run_in_background: true`)
 4. Write `session.json.diagnoses[]`. Update section 4. Mark G3.
 
 Commit: `"odyssey-improve({slug}): DIAGNOSE — root cause analysis"`
 
 ### A_ESCALATE_DIAGNOSIS
-`retries++`. < 3: `maestro delegate --role analyze`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → INCONCLUSIVE → S_RECORD.
+`retries++`. < 3: `maestro delegate --to claude --mode analysis`, new hypotheses, → S_DIAGNOSE. >= 3: Normal → request_user_input | `-y` → INCONCLUSIVE → S_RECORD.
 
 ### A_FIX
 Fix ALL diagnosed issues by severity tier (critical → high → medium → low within fix_threshold), one dimension at a time. After each tier, re-verify modified area — new findings append to current tier.
@@ -235,7 +239,7 @@ Commit: `"odyssey-improve({slug}): FIX — improvements implemented"`
 ### A_VERIFY
 1. Run tests covering modified areas
 2. Re-capture metrics, compare with `session.json.baseline_metrics`
-3. `maestro delegate --role review --mode analysis` (`run_in_background: true`) — check fix correctness, regressions, impact vs baseline
+3. `maestro delegate --to claude --mode analysis` (`run_in_background: true`) — check fix correctness, regressions, impact vs baseline
 4. `needs_rework` → S_FIX. `verified` → mark G4.
 5. Write `session.json.confirmation`. Update section 5.
 
@@ -263,7 +267,7 @@ Commit: `"odyssey-improve({slug}): GENERALIZE — pattern scan"`
 ### A_DISCOVER, A_RECORD
 Base shared_actions. Improve overrides:
 - **A_RECORD** section 8: before/after comparison table from baseline_metrics vs current measurements
-- **A_RECORD** section 9: learnings per Knowledge Persistence table
+- **A_RECORD** section 9: learnings per Knowledge Persistence table. **Confirmation gate**: Before writing spec entries, present proposed entries to user via `request_user_input` for confirmation. Skip confirmation only if `-y` flag is set.
 
 **Completion summary:**
 ```
@@ -297,7 +301,7 @@ Goals:      {done}/{total} ({skipped} skipped)
 | A_DIAGNOSE ambiguity | request_user_input | best-effort, deferred |
 | A_ESCALATE 3-strike | request_user_input | INCONCLUSIVE |
 
-### Goal Prompt convergence rules
+### Goal convergence rules
 
 ```
 Exhaust all findings (fix/issue/decision) until remaining_actionable == 0
@@ -333,6 +337,7 @@ Pending decisions must request_user_input — no report-only.
 </success_criteria>
 
 <next_step_routing>
+<!-- suggest-only — do NOT auto-execute. Present these as suggestions to the user. -->
 | Condition | Next |
 |-----------|------|
 | Security findings need deep investigation | `$odyssey-debug "<finding>"` |

package/.codex/skills/odyssey-planex/SKILL.md

@@ -7,6 +7,10 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 
 <base>@~/.maestro/workflows/odyssey-base-codex.md</base>
 
+<required_reading>
+Required reading: base (`odyssey-base-codex.md`) before any actions. Load and apply base invariants, execution discipline, and shared actions before proceeding.
+</required_reading>
+
 <purpose>
 Requirement-to-delivery closed loop: parse requirement -> define acceptance criteria ->
 plan -> execute -> verify -> fix gaps -> iterate until ALL criteria pass.
@@ -89,6 +93,7 @@ $ARGUMENTS
 <invariants>
 Base invariants apply. Additionally:
 6. **Acceptance criteria are sacred** -- no "close enough", no manual override without explicit escalation
+7. **Max-iteration failure is ESCALATED** -- when max iterations reached with failing criteria, status MUST be `ESCALATED` or `PARTIAL`, NEVER `ALL_PASSED`. Under `-y`, criteria remain `failed` with `deferred` decision, session status is `ESCALATED`. Lowering acceptance standards requires explicit user confirmation with original criteria, change reason, and `incomplete` marker recorded.
 </invariants>
 
 <self_iteration>
@@ -173,7 +178,7 @@ S_RECORD -> END
    - **Normal**: request_user_input to confirm/edit
    - **`-y`**: auto-derive, record `{"phase":"decision","type":"criteria-confirmation","status":"deferred"}`
 3. Search prior knowledge: `maestro search`, related sessions
-4. Write session.json + understanding.md S1. Mark G1 done. Display Goal Prompt
+4. Write session.json + understanding.md S1. Mark G1 done. call `create_goal` with phase_goals as success_criteria
 
 Commit: `"odyssey-planex({slug}): INTAKE -- requirement parsed"`
 
@@ -186,7 +191,7 @@ Commit: `"odyssey-planex({slug}): INTAKE -- requirement parsed"`
    MODE: analysis
    CONTEXT: @**/* | Criteria: {criteria_summary}
    EXPECTED: JSON [{task_id, title, description, criteria_refs, deps}]
-   " --role analyze --mode analysis
+   " --to claude --mode analysis
    ```
    Execute with `run_in_background: true`, wait for callback.
 3. Write session.json.plan, append evidence (planning), update understanding.md S2. Mark G2 done.
@@ -289,7 +294,7 @@ Execute with `run_in_background: true`, wait for callback.
 1. First attempt: normal dispatch
 2. Retry: `--resume planex-${slug}-${task_id}` with simplified prompt
 3. Final: fallback to Agent path
-4. All 3 fail -> mark task `blocked`, record checkpoint, continue remaining tasks
+4. All 3 fail -> mark task `blocked`, record checkpoint, continue remaining tasks. Blocked tasks make G3 `incomplete` — related acceptance criteria are marked `blocked`, and S_VERIFY/S_RECORD propagate the incomplete status.
 
 #### Step 4: Per-Task Evidence
 
@@ -382,7 +387,7 @@ Commit: `"odyssey-planex({slug}): VERIFY -- acceptance check"`
    MODE: analysis
    CONTEXT: @{modified_files} | Passing: {passing} | Fixed: {fixed}
    EXPECTED: JSON {verdict, regression_risk, concerns}
-   " --role review --mode analysis
+   " --to claude --mode analysis
    ```
 4. Append evidence (fix), update understanding.md S5 -> S_VERIFY
 
@@ -405,7 +410,7 @@ Mark G5 done. Commit: `"odyssey-planex({slug}): GENERALIZE -- pattern scan"`
 Base shared_actions. Mark G6 done. Commit: `"odyssey-planex({slug}): DISCOVER -- triage complete"`
 
 ### A_RECORD
-Base shared_actions. Learnings per Knowledge Persistence table.
+Base shared_actions. Learnings per Knowledge Persistence table. **Confirmation gate**: Before writing spec entries, present proposed entries to user via `request_user_input` for confirmation. Skip confirmation only if `-y` flag is set.
 
 **Completion summary:**
 ```
@@ -437,9 +442,9 @@ Commit: `"odyssey-planex({slug}): RECORD -- session summary"`
 | S_EXECUTE execution options | request_user_input (executor/review/verify) | use defaults (auto/Skip/Auto), `confirmed: true` |
 | S_EXECUTE task blocked (3 retries) | request_user_input: continue or stop | auto continue, log blocked |
 | S_VERIFY manual criterion | request_user_input | `deferred` |
-| S_VERIFY max iteration reached | request_user_input | auto accept, `deferred` |
+| S_VERIFY max iteration reached | request_user_input (continue/lower bar/accept) | mark status `ESCALATED`, record failing criteria as `deferred`, proceed to S_RECORD with `ESCALATED` status — NEVER mark as `ALL_PASSED` |
 
-### Goal Prompt convergence rules
+### Goal convergence rules
 
 ```
 Stop when acceptance_criteria[*] all status==passed
@@ -485,11 +490,12 @@ Max iterations (default 3) prevents infinite loops. Each iteration records crite
 - [ ] understanding.md S1-S8 updated per phase; phase_goals G1-G7 audited
 - [ ] Generalization + discovery completed (unless --skip-generalize)
 - [ ] Quality Gate self-iteration triggered when insufficient
-- [ ] Goal Prompt displayed once after intake; `-y` mode: no blocking prompts
+- [ ] `create_goal` called once after intake; `-y` mode: no blocking prompts
 - [ ] Session resumable via -c; completion summary output
 </success_criteria>
 
 <next_step_routing>
+<!-- suggest-only — do NOT auto-execute. Present these as suggestions to the user. -->
 | Condition | Next step |
 |-----------|-----------|
 | All criteria passed | `$odyssey-review-test-fix <changed-files>` |

package/.codex/skills/odyssey-review-test-fix/SKILL.md

@@ -6,6 +6,10 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 ---
 <base>@~/.maestro/workflows/odyssey-base-codex.md</base>
 
+<required_reading>
+Required reading: base (`odyssey-base-codex.md`) before any actions. Load and apply base invariants, execution discipline, and shared actions before proceeding.
+</required_reading>
+
 <purpose>
 archaeology → explore → multi-dimensional review → fix ALL findings → confirm → generalize → discover → persist. Zero-residual: every finding must have an action (fix/issue/decision).
 </purpose>
@@ -142,7 +146,7 @@ S_DISCOVER → S_RECORD      : done or max_loops
 <actions>
 
 ### A_INTAKE
-Parse target + flags → file list. Create SESSION_DIR, derive phase_goals[]. Search prior knowledge. Write session.json + section 1. Display Goal Prompt.
+Parse target + flags → file list. Create SESSION_DIR, derive phase_goals[]. Search prior knowledge. Write session.json + section 1. Call `create_goal` with phase_goals as success_criteria.
 
 ### A_ARCHAEOLOGY
 **spawn_agents_on_csv (Wave 1):**
@@ -156,10 +160,10 @@ spawn_agents_on_csv({ csv_path: "tasks.csv", id_column: "id",
   max_concurrency: 2, max_runtime_seconds: 300,
   output_csv_path: "wave-1-results.csv", output_schema: SHARED_OUTPUT_SCHEMA })
 ```
-Merge → evidence (phase: archaeology). CLI delegate `--role analyze`. Update section 2.
+Merge → evidence (phase: archaeology). CLI delegate `--to claude --mode analysis`. Update section 2.
 
 ### A_EXPLORE
-CLI delegate `--role explore` — call chains, error gaps, similar patterns. Write explore.json. Update section 3. Mark G2.
+CLI delegate `--to claude --mode analysis` — call chains, error gaps, similar patterns. Write explore.json. Update section 3. Mark G2.
 
 ### A_REVIEW
 **spawn_agents_on_csv (Wave 2):**
@@ -192,7 +196,7 @@ Remaining > 0 → retry (no max_loops limit). Unchanged 2 rounds → classify ea
 Blanket "pre-existing" forbidden.
 
 ### A_CONFIRM
-Run tests + CLI delegate zero-residual review (`--role review`).
+Run tests + CLI delegate zero-residual review (`--to claude --mode analysis`).
 - `remaining == 0 AND new == 0` → confirmed, mark G3
 - Otherwise → needs_rework → S_FIX
 
@@ -223,7 +227,7 @@ Mark G4.
 Base shared_actions. Review overrides: cross-phase loop tracking per base.
 
 ### A_RECORD
-Base shared_actions. Learnings per Knowledge Persistence table.
+Base shared_actions. Learnings per Knowledge Persistence table. **Confirmation gate**: Before writing spec entries, present proposed entries to user via `request_user_input` for confirmation. Skip confirmation only if `-y` flag is set.
 
 **Completion summary:**
 ```
@@ -248,7 +252,7 @@ Goals:  {done}/{total} ({skipped} skipped)
 | S_FIX re-review new findings | request_user_input | auto-append |
 | S_CONFIRM needs_rework | Display → S_FIX | auto proceed |
 
-### Goal Prompt convergence rules
+### Goal convergence rules
 
 ```
 Stop when review_result.remaining_actionable == 0, confirmation == confirmed,
@@ -274,10 +278,11 @@ Decision pending must request_user_input.
 - [ ] All dimensions reviewed, ALL findings fixed (remaining_actionable == 0), zero-residual confirmed
 - [ ] Per-tier re-review gate; every unfixed finding individually classified
 - [ ] Generalized with multi-layer scan (unless --skip-generalize); self-iteration on insufficient
-- [ ] understanding.md sections 1-8, phase_goals G1-G6 audited, Goal Prompt once, `-y` no blocking, -c resumable
+- [ ] understanding.md sections 1-8, phase_goals G1-G6 audited, `create_goal` called once, `-y` no blocking, -c resumable
 </success_criteria>
 
 <next_step_routing>
+<!-- suggest-only — do NOT auto-execute. Present these as suggestions to the user. -->
 | Condition | Next |
 |-----------|------|
 | Deeper debug needed | `$odyssey-debug "<finding>"` |

package/.codex/skills/odyssey-ui/SKILL.md

@@ -7,6 +7,10 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request
 
 <base>@~/.maestro/workflows/odyssey-base-codex.md</base>
 
+<required_reading>
+Required reading: base (`odyssey-base-codex.md`) before any actions. Load and apply base invariants, execution discipline, and shared actions before proceeding.
+</required_reading>
+
 <purpose>
 survey -> 6-dimension audit -> divergent creative exploration ->
 fix -> verify -> generalize -> discover -> persist.
@@ -153,7 +157,7 @@ S_RECORD   -> END           : complete
 2. Generate slug, create SESSION_DIR
 3. `maestro search` + Glob prior sessions + ARCHITECTURE.md + spec load ui/coding
 4. Derive `phase_goals[]` from flags (apply `skip_when`)
-5. Write `session.json` + `understanding.md` section 1, emit Goal Prompt
+5. Write `session.json` + `understanding.md` section 1, call `create_goal` with phase_goals as success_criteria
 
 Commit: `"odyssey-ui({slug}): INTAKE -- target parsed"`
 
@@ -208,7 +212,7 @@ TASK: Identify polish opportunities | Suggest delight moments | Evaluate visual
 MODE: analysis  CONTEXT: @{target_files} | Survey: {token_summary} | Audit: {top_findings}
 EXPECTED: JSON [{idea, category, impact, effort, description}]
 CONSTRAINTS: User-perceptible improvements only
-" --role analyze --mode analysis
+" --to claude --mode analysis
 ```
 Execute with `run_in_background: true`, then wait for callback.
 
@@ -225,7 +229,7 @@ Commit: `"odyssey-ui({slug}): FIX -- improvements applied"`
 
 ### A_VERIFY
 1. Run tests (lint, unit, visual regression)
-2. CLI-assisted: `maestro delegate --role review` -- visual correctness, interaction states, accessibility, responsive
+2. CLI-assisted: `maestro delegate --to claude --mode analysis` -- visual correctness, interaction states, accessibility, responsive
 3. `needs_rework` -> S_FIX. `verified` -> mark G4 done. Update section 5, write `confirmation`.
 
 Commit: `"odyssey-ui({slug}): VERIFY -- visual verification"`
@@ -250,7 +254,7 @@ Commit: `"odyssey-ui({slug}): GENERALIZE -- pattern scan"`
 ### A_DISCOVER, A_RECORD
 Base shared_actions. UI overrides:
 - **A_DISCOVER** routing per base triage logic
-- **A_RECORD** learnings per Knowledge Persistence table
+- **A_RECORD** learnings per Knowledge Persistence table. **Confirmation gate**: Before writing spec entries, present proposed entries to user via `request_user_input` for confirmation. Skip confirmation only if `-y` flag is set.
 
 **Completion summary:**
 ```
@@ -278,7 +282,7 @@ Goals:      {done}/{total} ({skipped} skipped)
 |----------------|--------|------|
 | A_FIX improvement confirmation | request_user_input | auto-proceed, `deferred` |
 
-### Goal Prompt convergence rules
+### Goal convergence rules
 
 ```
 Exhaustive iteration: process all audit + diverge findings (fix/issue/decision)
@@ -309,6 +313,7 @@ phase=decision pending items MUST request_user_input. No report-only items.
 </success_criteria>
 
 <next_step_routing>
+<!-- suggest-only — do NOT auto-execute. Present these as suggestions to the user. -->
 | Condition | Next |
 |-----------|------|
 | Finding needs deeper debug | `$odyssey-debug "<finding>"` |

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

@@ -16,7 +16,7 @@ Topology: layers as waves (L0->L1->L2->L3 sequential, scenarios within layer par
 $ARGUMENTS -- phase number and optional flags.
 
 **Flags**:
-- `-y, --yes`: Skip all confirmations
+- `-y, --yes`: Skip all confirmations (including CSV generation approval gate after S_CSV_GEN)
 - `-c, --concurrency N`: Max concurrent agents per layer (default: 5)
 - `--max-iter N`: Max outer iterations (default: 5; 1 = single-pass)
 - `--layer L`: Restrict to specific layer (L0|L1|L2|L3)
@@ -48,9 +48,17 @@ id,name,layer,priority,category,target_file,test_file,description,test_cases,fix
 ```
 
 **scenarios.csv column semantics**:
-- Input: id (AT-NNN), name, layer (L1/L2/L3 = wave order), priority (critical/high/medium), category (api_contract/business_rule/state_transition/user_flow/...), target_file (source file tested), test_file (test file path to create), description (what scenario validates), test_cases (semicolon-sep, each -> one it() block), fixtures (required mocks/fixtures, semicolon-sep), req_ref (REQ-NNN:AC-N or gap-id or empty), infrastructure_hints (framework + pattern refs from infra discovery)
-- Computed: prev_context (findings from prior layer scenarios, cross-layer propagation)
-- Output: status (pending->written->passed->failed->blocked), red_result (expected_fail/unexpected_fail/pass), findings (patterns discovered, notes for dependents, max 500 chars), error
+
+**Input columns** (written by orchestrator into wave CSV):
+id (AT-NNN), name, layer (L1/L2/L3 = wave order), priority (critical/high/medium), category (api_contract/business_rule/state_transition/user_flow/...), target_file (source file tested), test_file (test file path to create), description (what scenario validates), test_cases (semicolon-sep, each -> one it() block), fixtures (required mocks/fixtures, semicolon-sep), req_ref (REQ-NNN:AC-N or gap-id or empty), infrastructure_hints (framework + pattern refs from infra discovery)
+
+**Computed column** (added to wave CSV by orchestrator before spawn):
+prev_context (findings from prior layer scenarios, cross-layer propagation)
+
+**Lifecycle columns** (exist ONLY in master CSV, populated during merge from output_schema results -- NEVER included in wave CSV input):
+status (pending->written->passed->failed->blocked), red_result (expected_fail/unexpected_fail/pass), classification, fix_code, evidence, findings (patterns discovered, notes for dependents, max 500 chars), files_modified, error
+
+**Column separation rule**: Wave CSV (input to `spawn_agents_on_csv`) contains Input columns + prev_context only. Lifecycle columns are NEVER passed to workers. Workers return values exclusively via `output_schema`. During merge: `result_status` -> master `status`; other output fields copied into matching lifecycle columns.
 
 ### diagnosis.csv (Iteration Phase)
 
@@ -107,7 +115,7 @@ S_INFRA:
   -> S_CSV_GEN      DO: detect framework, read 2-3 existing tests, build infrastructure_hints
 
 S_CSV_GEN:
-  -> S_L0           DO: build scenarios.csv, set cross-layer prev_context
+  -> S_L0           DO: build scenarios.csv, set cross-layer prev_context, then confirm with user via request_user_input (skip if -y/--yes): display scenario count per layer, priority distribution, and sample rows; user approves or adjusts before execution
   -> END            WHEN: --dry-run (plan only)
 
 S_L0: