Maestro Odyssey

• background: false is the default. Use foreground dispatch whenever the result determines the current answer or next action.
• Use background: true only for independent work. If this turn must consume a background result, call observe exactly once with action: "wait" and a bounded timeout before continuing; never continue independently while the result is pending.
• Otherwise end the turn and wait for the automatic teammate-complete notification. Do not rely on SendMessage, team_msg, or hook callbacks as completion signals.
• Never silently ignore an unfinished dispatch.

If any required file above was not expanded into context by the host, or its content is no longer in context, Read it explicitly before executing any step.

Mode selection precedence: explicit --mode <name> > intent keyword auto-detection > [@ask] AskUserQuestion (Normal) / error E000 (-y).

Auto-detection from <intent> keywords (first match wins, ordered):

Keyword matching: case-insensitive substring match against the intent text. Multi-word keywords require all words present (not necessarily adjacent). First matching row wins (ordered by specificity).

Ambiguous / no match → Normal: [@ask] AskUserQuestion (7-way mode pick) | -y: E000.

Mode registry:

CONFIRM and VERIFY are synonymous — both refer to the post-fix validation phase. Mode workflow files use mode-specific naming; semantics are identical.

The back half is identical across all modes: GENERALIZE → DISCOVER → RECORD → END (see odyssey-base.md §Shared Back-Half).

On mode resolved: read the deferred workflow file for that mode + odyssey-base.md, then execute.

Universal flags: --mode <name> mode selector | --skip-fix audit/diagnose only, skip fix+verify | --skip-generalize skip GENERALIZE+DISCOVER | -y skip all confirmation interactions (including delegate/agent confirmations in execution phases), use default choices; decisions skipped this way are recorded as deferred; never bypasses mode ambiguity (E000), INTAKE gate blockers, escalation | -c resume the most recent unfinished Session of the SAME mode via exact Session resolution: locate it with maestro session list --json + maestro session status --session {session_id} --json (both read-only), re-attach context with maestro session resume-view and the brief-result/3.0 Resume Packet via run brief (exact invocation per run-mode.md), then continue the chain with fenced maestro run next / run check / run complete --advance. If --mode conflicts with the resumed Session's mode → E003 (mode mismatch); no history → ignore -c, create new Session | --heartbeat /loop periodic progress

Mode-scoped flags:

--skip-fix applicability: security and defensive modes ignore (read-only, no fix phase); planex skips FIX loop but retains EXECUTE+VERIFY; debug/review/improve/ui skip FIX+VERIFY/CONFIRM. --skip-fix + --skip-verify on planex = PLAN only (no execution).

Mode-scoped flags passed to inapplicable mode: emit W008 warning and ignore the flag.

Session creation: follow run-mode.md exactly. Negotiate capabilities, then use the receipt-chained self-start path: open an empty Session with participant == actor and a unique open request ID, insert odyssey-<mode> plus every mode/domain argument through fenced repeatable --arg, and dispatch it with fenced run next using a third request ID. Every mutation consumes the exact revision returned by the preceding receipt. Consume the resulting birth packet's resolved task and structured executable continuation; never pass task prose via --input. A direct machine-protocol run create is allowed only with positional domain arguments, explicit --session/--run/--step, identical participant/actor values, request ID/reason, exact CAS revision, and --input values restricted to sealed same-Session Artifact IDs.

Session: {run_dir}/outputs/ Output: session.json | evidence.ndjson | understanding.md | explore.json (debug/review only) | anchors.json (defensive only)

Output boundary: ALL session artifacts MUST target the run outputs directory ({run_dir}/outputs/) only. .workflow/state.json and all sessions/<sid>/ protocol files are runtime-owned — a workflow never writes them. Source code modifications during fix/execute phases are in-scope but MUST be committed per action. NEVER write session artifacts outside {run_dir}/outputs/.

session.json — shared core + mode fields:

{ "mode": "debug|improve|planex|review|security|defensive|ui",
  "target": "", "dimensions": [],
  "patterns": [], "confirmation": null, "generalization_stats": null,
  "cross_phase_loops": 0 }

Each mode extends the core — see the mode's workflow file for session fields.

Commit convention: "odyssey-{mode}({slug}): {STATE} — {summary}" (mode = active mode short name; review mode uses odyssey-review).

1. Evidence append-only — never delete or overwrite evidence.ndjson entries.
2. Phase goal tracking — mark each goal done/failed before transition; no silent skips.
3. Generalize is mandatory — GENERALIZE and DISCOVER execute unless skip_generalize == true. Prior-phase convergence, "no findings / all verified / zero remaining," or context pressure are NOT valid skip reasons. The phase itself determines whether patterns exist.
4. Zero-residual (improve/review/ui) — every finding MUST have a concrete action (fix / issue / decision). "Report and shelve" and blanket "pre-existing" skips are forbidden.
5. Read-only (security, defensive) — NEVER modify source code, configuration, or dependencies. Security and defensive audits produce reports only; fixes route to --mode improve.
6. Acceptance criteria are sacred (planex) — no "close enough", no manual override without explicit escalation.
7. Browser is truth (ui) — verify in real rendering, not just code review. Diverge before converge.
8. Goal tracking 与 session 双写 — 各 phase 进入/退出时同步创建/更新 goal，补充 session.json 的 UI 可见进度。

Shared Phase Gates (MANDATORY, BLOCKING)

• INTAKE gate: mode resolved, target/requirement resolved, SESSION_DIR created, session.json initialized (with baseline_metrics for improve; acceptance_criteria for planex), phase_goals[] derived from flags, understanding.md §1 written. BLOCKED if no target (E001) / no requirement (planex E001) / target path not found (E002) / mode unresolved (E000).
• GENERALIZE gate: ALL 3 layers (syntax/semantic/structural) attempted with evidence logged; generalization_stats written with by_layer entries for all 3 layers; generalize goal marked. Any layer not attempted = thoroughness-floor violation (BLOCKED).
• DISCOVER gate: all hits triaged with per-item classification and reason; remaining_actionable == 0 OR loops >= max_loops with per-item reasons logged; discover goal marked. Unclassified hits = BLOCKED.

Mode-specific phase gates (Discovery, Audit, FIX, VERIFY/CONFIRM) are defined in each mode's workflow file.