oh-my-codex 0.17.3 → 0.18.1

package/plugins/oh-my-codex/skills/plan/SKILL.md

@@ -94,11 +94,11 @@ Jumping into code without understanding requirements leads to rework, scope cree
    b. Deduplicate and categorize the suggestions
    c. Update the plan file in `.omx/plans/` with the accepted improvements (add missing details, refine steps, strengthen acceptance criteria, ADR updates, etc.)
    d. Note which improvements were applied in a brief changelog section at the end of the plan
-   e. Before any execution handoff, derive an explicit **available-agent-types roster** from the known prompt catalog and add concrete **follow-up staffing guidance** for both `$ralph` and `$team` (recommended roles, counts, suggested reasoning levels by lane, and why each lane exists)
-   f. Add a product-facing **Goal-Mode Follow-up Suggestions** section: recommend `$ultragoal` by default for general goal-oriented follow-up, `$autoresearch-goal` when the context is a research project, and `$performance-goal` when the context is an optimization or performance project. Keep these suggestions alongside the Ralph/team paths rather than replacing them when implementation delivery is still the main need. For durable-goal work that is also parallelizable, explicitly recommend **Team + Ultragoal**: Ultragoal remains leader-owned goal/ledger state and Team returns checkpoint-ready execution evidence.
-   g. For the `$team` path, add an explicit launch-hint block with concrete `omx team` / `$team` commands and a **team verification path** (what team proves before shutdown, what Ralph verifies after handoff). Distinguish Team + Ultragoal from a later Ralph follow-up: Team handles coordinated parallel lanes; Ralph is only for persistent sequential single-owner verification/fix pressure when needed.
+   e. Before any execution handoff, derive an explicit **available-agent-types roster** from the known prompt catalog and add concrete **follow-up staffing guidance** for `$ultragoal` and `$team` (recommended roles, counts, suggested reasoning levels by lane, and why each lane exists), plus an explicit `$ralph` fallback note only when persistent single-owner verification is intentionally selected
+   f. Add a product-facing **Goal-Mode Follow-up Suggestions** section: recommend `$ultragoal` by default for general goal-oriented follow-up, `$autoresearch-goal` when the context is a research project, and `$performance-goal` when the context is an optimization or performance project. Keep these suggestions alongside the Team path and any explicit Ralph fallback rather than replacing implementation-delivery guidance. For durable-goal work that is also parallelizable, explicitly recommend **Team + Ultragoal**: Ultragoal remains leader-owned goal/ledger state and Team returns checkpoint-ready execution evidence.
+   g. For the `$team` path, add an explicit launch-hint block with concrete `omx team` / `$team` commands and a **team verification path** (what Team proves before shutdown and what Ultragoal checkpoints as durable completion evidence). Distinguish Team + Ultragoal from any explicit Ralph fallback: Team handles coordinated parallel lanes; Ultragoal is the default durable follow-up/ledger owner, and Ralph is only an explicitly requested legacy-style persistent sequential verification/fix lane when needed.
 7. On Critic approval (with improvements applied): *(--interactive only)* If running with `--interactive`, use `AskUserQuestion` / the structured question UI to present the plan with these options:
-   - **Approve and execute** — proceed to implementation via ralph+ultrawork
+   - **Approve durable goal execution** — proceed via `$ultragoal` by default (optionally with `$team` for parallel lanes)
    - **Approve and implement via team** — proceed to implementation via coordinated parallel team agents
    - **Start goal-mode follow-up** — proceed via `$ultragoal` by default, or `$autoresearch-goal` / `$performance-goal` when the approved plan specifically fits research validation or measurable optimization
    - **Request changes** — return to step 1 with user feedback
@@ -106,7 +106,7 @@ Jumping into code without understanding requirements leads to rework, scope cree
    If NOT running with `--interactive`, output the final approved plan and stop. Do NOT auto-execute.
 8. *(--interactive only)* User chooses via the structured question UI (never ask for approval in plain text when a structured surface is available)
 9. On user approval (--interactive only):
-   - **Approve and execute**: **MUST** invoke `$ralph` with the approved plan path from `.omx/plans/` as context **plus the explicit available-agent-types roster, suggested reasoning levels, concrete role allocation guidance, and direct launch hints for Ralph follow-up work**. Do NOT implement directly. Do NOT edit source code files in the planning agent. The ralph skill handles execution via ultrawork parallel agents.
+   - **Approve durable goal execution**: **MUST** invoke `$ultragoal` with the approved plan path from `.omx/plans/` as context **plus the explicit available-agent-types roster, suggested reasoning levels, concrete role allocation guidance, and direct launch hints for Ultragoal follow-up work**. Use `$team` alongside Ultragoal when parallel lanes are warranted. Do NOT implement directly. Do NOT edit source code files in the planning agent. Ralph is not the default follow-up; only invoke `$ralph` when the user explicitly selects a legacy/persistent single-owner execution lane.
    - **Approve and implement via team**: **MUST** invoke `$team` with the approved plan path from `.omx/plans/` as context **plus the explicit available-agent-types roster, suggested reasoning levels, concrete staffing / worker-role allocation guidance, explicit `omx team` / `$team` launch hints, and the team verification path**. Do NOT implement directly. The team skill coordinates parallel agents across the staged pipeline for faster execution on large tasks.
    - **Start goal-mode follow-up**: **MUST** invoke the selected goal workflow with the approved plan path and appropriate success context: `$ultragoal` as the default goal-mode path, `$autoresearch-goal` for research projects, or `$performance-goal` for optimization/performance projects with measurable evaluator criteria. Do NOT implement directly in the planning agent.
 
@@ -147,7 +147,7 @@ Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 - **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await the Architect result before issuing the Critic call.
 - In consensus mode, default to RALPLAN-DR short mode; enable deliberate mode on `--deliberate` or explicit high-risk signals (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage)
 - In consensus mode with `--interactive`: use `AskUserQuestion` / the structured question UI for the user feedback step (step 2) and the final approval step (step 7) -- never ask for approval in plain text when a structured surface is available. Without `--interactive`, auto-proceed through planning steps without pausing. Output the final plan without execution.
-- In consensus mode with `--interactive`, on user approval **MUST** invoke the selected follow-up lane from step 9 (`$ralph`, `$team`, `$ultragoal`, `$autoresearch-goal`, or `$performance-goal`) -- never implement directly in the planning agent
+- In consensus mode with `--interactive`, on user approval **MUST** invoke the selected follow-up lane from step 9 (`$ultragoal`, `$team`, `$autoresearch-goal`, `$performance-goal`, or explicit `$ralph` fallback) -- never implement directly in the planning agent
 - In consensus mode, execution follow-up handoff **MUST** include an explicit available-agent-types roster plus concrete staffing / role-allocation guidance grounded in that roster, suggested reasoning levels by lane, product-facing goal-mode follow-up suggestions (`$ultragoal` by default, `$autoresearch-goal` for research projects, `$performance-goal` for optimization/performance projects), explicit `omx team` / `$team` launch hints, and a team verification path. For parallelizable durable-goal plans, recommend Team + Ultragoal with leader-owned checkpointing from Team evidence; reserve Ralph for persistent sequential single-owner verification/fix follow-up.
 </Tool_Usage>
 
@@ -212,8 +212,8 @@ Why bad: Decision fatigue. Present one option with trade-offs, get reaction, the
 <Escalation_And_Stop_Conditions>
 - Stop interviewing when requirements are clear enough to plan -- do not over-interview
 - In consensus mode, stop after 5 Planner/Architect/Critic iterations and present the best version
-- Consensus mode outputs the plan by default; with `--interactive`, user can approve and hand off to ralph/team
-- If the user says "just do it" or "skip planning", **MUST** invoke `$ralph` to transition to execution mode. Do NOT implement directly in the planning agent.
+- Consensus mode outputs the plan by default; with `--interactive`, user can approve and hand off to ultragoal/team, with Ralph only as an explicit legacy/persistent single-owner lane
+- If the user says "just do it" or "skip planning", **MUST** invoke `$ultragoal` to transition to durable goal execution mode by default; use `$ralph` only when the user explicitly asks for that fallback. Do NOT implement directly in the planning agent.
 - Escalate to the user when there are irreconcilable trade-offs that require a business decision
 </Escalation_And_Stop_Conditions>
 

package/plugins/oh-my-codex/skills/ralph/SKILL.md

@@ -127,6 +127,13 @@ Use the CLI-first state surface for Ralph lifecycle state (`omx state write/read
   `omx state write --input '{"mode":"ralph","current_phase":"verifying"}' --json` or `omx state write --input '{"mode":"ralph","current_phase":"fixing"}' --json`
 - **On completion** (only after the completion audit passes with real evidence):
   `omx state write --input '{"mode":"ralph","active":false,"current_phase":"complete","completed_at":"<now>","completion_audit":{"passed":true,"prompt_to_artifact_checklist":["<requirement mapped to artifact/evidence>"],"verification_evidence":["<fresh test/build/lint command and result>"]}}' --json`
+- **Before the final answer**:
+  1. Run fresh verification and read the output.
+  2. Build `prompt_to_artifact_checklist` entries that map every user requirement, workflow gate, named file, command, PR/delivery requirement, and stop condition to a concrete artifact or evidence item.
+  3. Build `verification_evidence` entries with concrete commands, exit status, files inspected, PR URLs, or other machine-checkable evidence.
+  4. Write the Ralph completion state with a top-level `completion_audit` field on the Ralph state object. Do not write bare top-level `prompt_to_artifact_checklist` or `verification_evidence` fields by themselves; the Stop gate will reject them.
+  5. Read the state back with `omx state read --input '{"mode":"ralph"}' --json` and verify `completion_audit.passed === true`, a non-empty checklist, and non-empty verification evidence before producing the final answer.
+  6. If Codex goal mode is active, call `update_goal({status:"complete"})` only after this Ralph audit read-back succeeds.
 - **On cancellation/cleanup**:
   run `$cancel` (which should call `omx state clear --input '{"mode":"ralph"}' --json`)
 

package/plugins/oh-my-codex/skills/ralplan/SKILL.md

@@ -54,9 +54,9 @@ The consensus workflow:
    d. Return to Critic evaluation
    e. Repeat this loop until Critic returns `APPROVE` or 5 iterations are reached
    f. If 5 iterations are reached without `APPROVE`, present the best version to the user
-6. On Critic approval *(--interactive only)*: If `--interactive` is set, use the structured question UI to present the plan with approval options (Approve and execute via ralph / Approve and implement via team / Start a goal-mode follow-up / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups), an explicit available-agent-types roster, concrete follow-up staffing guidance for both `ralph` and `team`, suggested reasoning levels by lane, explicit `omx team` / `$team` launch hints, a concrete **team verification** path, and a product-facing **Goal-Mode Follow-up Suggestions** section. Recommend `$ultragoal` by default for goal-mode follow-up, use `$autoresearch-goal` instead when the context is a research project, and use `$performance-goal` instead when the context is an optimization or performance project. Otherwise, output the final plan and stop.
-7. *(--interactive only)* User chooses: Approve (ralph, team, or a goal-mode follow-up), Request changes, or Reject
-8. *(--interactive only)* On approval: invoke `$ralph` for sequential execution, `$team` for parallel team execution, or the selected goal-mode follow-up (`$ultragoal`, `$autoresearch-goal`, or `$performance-goal`) with the approved plan and matching success/evaluator context -- never implement directly. Preserve the explicit available-agent-types roster, reasoning-by-lane guidance, role/staffing allocation guidance, launch hints, and verification-path guidance from the approved plan for Ralph/team paths.
+6. On Critic approval *(--interactive only)*: If `--interactive` is set, use the structured question UI to present the plan with approval options (Approve durable goal execution via ultragoal / Approve and implement via team / Explicit Ralph fallback / Start specialized goal-mode follow-up / Request changes / Reject). Final plan must include ADR (Decision, Drivers, Alternatives considered, Why chosen, Consequences, Follow-ups), an explicit available-agent-types roster, concrete follow-up staffing guidance for `$ultragoal` and `$team`, plus an explicit `$ralph` fallback note when persistent single-owner verification is intentionally selected, suggested reasoning levels by lane, explicit `omx team` / `$team` launch hints, a concrete **team verification** path, and a product-facing **Goal-Mode Follow-up Suggestions** section. Recommend `$ultragoal` by default for goal-mode follow-up, use `$autoresearch-goal` instead when the context is a research project, and use `$performance-goal` instead when the context is an optimization or performance project. Otherwise, output the final plan and stop.
+7. *(--interactive only)* User chooses: Approve (`$ultragoal` durable goal execution, `$team`, explicit `$ralph` fallback, or a specialized goal-mode follow-up), Request changes, or Reject
+8. *(--interactive only)* On approval: invoke `$ultragoal` for default durable sequential execution, `$team` for parallel team execution, the selected specialized goal-mode follow-up (`$autoresearch-goal` or `$performance-goal`), or `$ralph` only when the user explicitly selects that fallback with the approved plan and matching success/evaluator context -- never implement directly. Preserve the explicit available-agent-types roster, reasoning-by-lane guidance, role/staffing allocation guidance, launch hints, and verification-path guidance from the approved plan for Ultragoal/team paths and any explicit Ralph fallback.
 
 > **Important:** Steps 3 and 4 MUST run sequentially. Do NOT issue both agent calls in the same parallel batch. Always await the Architect result before invoking Critic.
 
@@ -70,7 +70,7 @@ When ralplan outputs a final handoff or asks the user to choose a next lane, inc
 - `$autoresearch-goal` — research-project follow-up when the plan centers on a question, literature/reference gathering, evaluator-backed research, or a professor/critic-style research deliverable.
 - `$performance-goal` — optimization/performance follow-up when the plan centers on speed, latency, throughput, memory, benchmark, or other measurable performance work.
 
-Keep `$ralph` and `$team` as first-class execution options where appropriate: use Ralph for persistent single-owner completion/verification pressure and team for coordinated parallel implementation. For parallelizable durable-goal delivery, recommend `$ultragoal` + `$team` together: Ultragoal remains the leader-owned `.omx/ultragoal` ledger/Codex-goal wrapper while Team runs parallel lanes and returns checkpoint-ready evidence. Do not present the goal-mode options as replacements for Ralph/team when the task is mainly implementation delivery; present them as better fits when durable goal tracking, research validation, or performance evaluators are the primary need.
+Keep `$team` as a first-class execution option and keep `$ralph` available only as an explicit fallback where appropriate: use Ultragoal as the default durable goal-mode follow-up, Team for coordinated parallel implementation, and Ralph only for intentionally selected persistent single-owner completion/verification pressure. For parallelizable durable-goal delivery, recommend `$ultragoal` + `$team` together: Ultragoal remains the leader-owned `.omx/ultragoal` ledger/Codex-goal wrapper while Team runs parallel lanes and returns checkpoint-ready evidence. Do not present Ralph as the recommended follow-up when durable goal tracking is needed; present Ultragoal as the superseding default, with Team for parallel delivery and Ralph only as an explicit fallback when its narrow persistence loop is specifically desired.
 
 ## Pre-context Intake
 
@@ -86,7 +86,7 @@ Before consensus planning or execution handoff, ensure a grounded context snapsh
    - unknowns/open questions
    - likely codebase touchpoints
 4. If ambiguity remains high, gather brownfield facts first. When session guidance enables `USE_OMX_EXPLORE_CMD`, prefer `omx explore` for simple read-only repository lookups with narrow, concrete prompts; otherwise use the richer normal explore path. Then run `$deep-interview --quick <task>` before continuing.
-5. If the plan depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, auto-delegate `researcher` before finalizing the planning handoff so execution does not start from repo-local recall alone.
+5. If the plan depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, use `$best-practice-research` as the bounded evidence wrapper and auto-delegate `researcher` for the official/upstream lookup before finalizing the planning handoff so execution does not start from repo-local recall alone.
 
 Do not hand off to execution modes until this intake is complete; if urgency forces progress, explicitly document the risk tradeoffs.
 

package/plugins/oh-my-codex/skills/team/SKILL.md

@@ -126,7 +126,7 @@ When `$team` is used as a follow-up mode from ralplan, carry forward the approve
 - state the recommended headcount and role counts
 - state the suggested reasoning level for each lane when available
 - explain why each lane exists (delivery, verification, specialist support)
-- include an explicit launch hint (`omx team N "<task>"` / `$team N "<task>"`) for the coordinated team run; mention a later separate Ralph follow-up only when genuinely needed
+- include an explicit launch hint (`omx team N "<task>"` / `$team N "<task>"`) for the coordinated team run; mention `$ultragoal` as the default durable follow-up/ledger path; mention a later separate Ralph follow-up only when explicitly requested or genuinely needed as a fallback
 - if the ideal role is unavailable, choose the closest role from the roster and say so
 
 ## Current Runtime Behavior (As Implemented)

package/plugins/oh-my-codex/skills/ultragoal/SKILL.md

@@ -9,11 +9,13 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
 
 ## Purpose
 
-`ultragoal` turns a brief into repo-native artifacts and then drives a Codex goal safely through goal tools. New plans default to an aggregate Codex goal for the whole ultragoal run while OMX tracks G001/G002 story progress in the ledger.
+`ultragoal` turns a brief into repo-native artifacts and then drives a Codex goal safely through goal tools. New plans default to a stable pointer-style aggregate Codex goal for the whole durable plan in `.omx/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while OMX tracks G001/G002 story progress in the ledger. Ultragoal does not call Codex `/goal clear`; before multiple sequential ultragoal runs in one Codex session/thread, manually run `/goal clear` in the Codex UI so the previous completed aggregate goal does not block or confuse the next `create_goal`.
 
 - `.omx/ultragoal/brief.md`
 - `.omx/ultragoal/goals.json`
-- `.omx/ultragoal/ledger.jsonl`
+- `.omx/ultragoal/ledger.jsonl` (checkpoint and structured steering audit events)
+
+Existing aggregate plans with the legacy enumerated objective are migrated to the stable pointer objective on read, persisted to `goals.json`, retained in `codexObjectiveAliases` for already-active hidden Codex goal reconciliation, and audited with an `aggregate_objective_migrated` ledger entry.
 
 ## Create goals
 
@@ -21,7 +23,7 @@ Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durabl
    - `omx ultragoal create-goals --brief "<brief>"`
    - `omx ultragoal create-goals --brief-file <path>`
    - `cat <brief> | omx ultragoal create-goals --from-stdin`
-   - `omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"` only when one fresh Codex thread per story is explicitly preferred
+   - `omx ultragoal create-goals --codex-goal-mode per-story --brief "<brief>"` only when one Codex goal context per story is explicitly preferred
 2. Inspect `.omx/ultragoal/goals.json` and refine if needed.
 
 ## Complete goals
@@ -43,6 +45,36 @@ Loop until `omx ultragoal status` reports all goals complete:
    `omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json <get_goal-json-or-path>`
 11. Resume failed goals with `omx ultragoal complete-goals --retry-failed`.
 
+## Dynamic steering
+
+Use `omx ultragoal steer` when real findings or blockers prove the current story decomposition should change while the aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.
+
+Allowed mutation kinds are:
+
+- `add_subgoal`
+- `split_subgoal`
+- `reorder_pending`
+- `revise_pending_wording`
+- `annotate_ledger`
+- `mark_blocked_superseded`
+
+Examples:
+
+```sh
+omx ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "Validate the blocker and report evidence." --evidence "log/test output" --rationale "The blocker changes the safe execution order." --json
+omx ultragoal steer --directive-json ./steering.json --json
+```
+
+Steering invariants:
+
+- Do not edit the aggregate Codex objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to `.omx/ultragoal/goals.json` and `.omx/ultragoal/ledger.jsonl`, not an enumeration of initial goal ids.
+- Do not hard-delete goals, auto-complete work, weaken verification, or silently mutate `.omx/ultragoal`.
+- Accepted and rejected attempts append structured audit entries to `.omx/ultragoal/ledger.jsonl`.
+- Superseded goals remain in `goals.json` with steering metadata and are skipped for scheduling.
+- Blocked goals without replacements are skipped for scheduling but still block final completion until later explicit steering replaces or supersedes them.
+
+UserPromptSubmit uses the same steering API only for structured directives such as `OMX_ULTRAGOAL_STEER: { ... }`, `omx.ultragoal.steer: { ... }`, or `omx ultragoal steer: { ... }`. Normal prose does not mutate state, and repeated prompt-submit directives dedupe by prompt signature or idempotency key.
+
 ## Use Ultragoal and Team together
 
 Use ultragoal and team together for a durable Ultragoal story that benefits from parallel execution. Ultragoal remains leader-owned: `.omx/ultragoal/goals.json` stores the story plan and `.omx/ultragoal/ledger.jsonl` stores checkpoints. Team is the parallel execution engine and returns task/evidence status to the leader.
@@ -69,7 +101,7 @@ The final ultragoal story is not complete until the active agent has run the fin
    omx ultragoal record-review-blockers --goal-id <id> --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json <active-get-goal-json-or-path>
    ```
 
-   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the Codex goal active, and lets `omx ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need a fresh/available Codex goal context because the old per-story Codex goal remains active/incomplete.
+   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the Codex goal active, and lets `omx ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need an available Codex goal context because the old per-story Codex goal remains active/incomplete.
 
 6. If review is clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with a structured final gate:
 
@@ -90,6 +122,8 @@ The final ultragoal story is not complete until the active agent has run the fin
 ## Constraints
 
 - The shell command cannot directly invoke Codex interactive `/goal`; it emits a model-facing handoff for the active Codex agent.
+- Ultragoal intentionally does not invoke `/goal clear` or hidden `thread/goal/clear`; the model-facing tool surface only provides `get_goal`, `create_goal`, and `update_goal`.
+- After a completed aggregate ultragoal run, clear the Codex goal manually with `/goal clear` before starting another ultragoal run in the same session/thread.
 - Never call `create_goal` when `get_goal` reports a different active goal.
 - Never call `update_goal` unless the aggregate run or legacy per-story goal is actually complete.
 - In aggregate mode, intermediate story checkpoints require a matching `active` Codex snapshot; final story completion requires a matching `complete` snapshot after `update_goal`.

package/plugins/oh-my-codex/skills/ultrawork/SKILL.md

@@ -16,7 +16,7 @@ Ultrawork is a parallel execution engine for high-throughput task completion. It
 
 <Do_Not_Use_When>
 - Task requires guaranteed completion with persistence, architect verification, or deslop/reverification -- use `ralph` instead (Ralph includes ultrawork)
-- Task requires a full autonomous pipeline -- use `autopilot` instead (autopilot includes Ralph which includes ultrawork)
+- Task requires a full autonomous pipeline -- use `autopilot` instead (autopilot defaults to Ultragoal, with Team/parallel execution used only when needed)
 - There is only one sequential task with no parallelism opportunity -- execute directly or delegate to a single `executor`
 - The request is still in plan-consensus mode -- keep planning artifacts in `ralplan` until execution is explicitly authorized
 - User needs session persistence for resume -- use `ralph`, which adds persistence on top of ultrawork

package/prompts/planner.md

@@ -59,7 +59,7 @@ Leave execution with a right-sized, evidence-grounded plan: scope, steps, accept
 - Codebase facts come from inspection.
 - Plan is saved to `.omx/plans/{name}.md`.
 - User confirmation is obtained before handoff.
-- Consensus mode includes complete RALPLAN-DR, ADR, an explicit available-agent-types roster, staffing guidance for team and ralph follow-up paths, product-facing goal-mode follow-up suggestions (`$ultragoal` generally and by default, `$autoresearch-goal` for research projects, `$performance-goal` for optimization/performance projects), suggested reasoning levels by lane, launch hints, and a team verification path when needed.
+- Consensus mode includes complete RALPLAN-DR, ADR, an explicit available-agent-types roster, staffing guidance for ultragoal and team follow-up paths, plus explicit Ralph fallback guidance, product-facing goal-mode follow-up suggestions (`$ultragoal` generally and by default because it supersedes Ralph for durable goal follow-up, `$autoresearch-goal` for research projects, `$performance-goal` for optimization/performance projects), suggested reasoning levels by lane, launch hints, and a team verification path when needed.
 </success_criteria>
 
 <tools>

package/prompts/researcher.md

@@ -7,15 +7,16 @@ You are Researcher (Librarian). Produce docs-first, version-aware external techn
 </identity>
 
 <goal>
-Identify the authoritative documentation set, establish version/date context, gather the smallest reliable evidence set, and return guidance the caller can reuse. You own external truth for an already chosen technology; you do not inspect repo usage, implement code, decide architecture, or compare dependencies.
+Identify the authoritative documentation set, establish version/date context, gather the smallest reliable evidence set, and return guidance the caller can reuse. You own external truth and current best-practice evidence for an already chosen technology; you do not inspect repo usage, implement code, decide architecture, or compare dependencies.
 </goal>
 
 <constraints>
 <scope_guard>
-- Prefer official documentation, API references, release notes, changelogs, and upstream source material over third-party summaries.
+- Prefer official documentation, API references, release notes, changelogs, standards, maintainer guidance, and upstream source material over third-party summaries.
 - Always include source URLs for important claims.
+- For current best-practice claims, state the relevant date, version, release channel, or uncertainty.
 - Flag stale, undocumented, conflicting, or version-mismatched information.
-- Separate official docs evidence from source-reference evidence.
+- Separate official docs evidence from source-reference evidence and supplemental third-party evidence.
 - Route dependency adoption/upgrade/replacement decisions to `dependency-expert`; route repo-local usage and migration-surface mapping to `explore`.
 </scope_guard>
 
@@ -31,7 +32,8 @@ Classify the request before searching:
 - Conceptual docs question: concepts, guarantees, lifecycle, configuration, official guidance.
 - Implementation reference lookup: APIs, options, signatures, examples, limits, migration steps.
 - Context/history lookup: release notes, changelog entries, deprecations, behavior changes.
-- Comprehensive research: combined docs, reference, and history answer.
+- Current best-practice research: official/upstream recommendations, standards, maintainer guidance, and dated/versioned practice for an already chosen technology.
+- Comprehensive research: combined docs, reference, history, and best-practice answer.
 </request_classification>
 
 <execution_loop>
@@ -47,15 +49,15 @@ Classify the request before searching:
 
 <success_criteria>
 - Request type and search path are explicit.
-- Official docs are primary where available.
-- Version certainty/uncertainty is stated.
+- Official docs/upstream sources are primary where available.
+- Version/date certainty or uncertainty is stated, especially for current best-practice claims.
 - Examples remain secondary to docs.
-- Docs evidence and source-reference evidence are separated.
+- Docs evidence, source-reference evidence, and supplemental third-party evidence are separated.
 - The answer is reusable without extra lookup.
 </success_criteria>
 
 <tools>
-Use web search/fetch for official docs, versioned references, release notes, migration guides, and upstream source. Use local reads only to sharpen the external research question.
+Use web search/fetch for official docs, versioned references, release notes, migration guides, standards, maintainer guidance, and upstream source. Use local reads only to sharpen the external research question.
 </tools>
 
 <style>
@@ -63,7 +65,7 @@ Use web search/fetch for official docs, versioned references, release notes, mig
 ## Research: [Query]
 
 ### Request Type
-[Conceptual docs question | Implementation reference lookup | Context/history lookup | Comprehensive research]
+[Conceptual docs question | Implementation reference lookup | Context/history lookup | Current best-practice research | Comprehensive research]
 
 ### Direct Answer
 [Actionable answer]
@@ -80,6 +82,9 @@ Use web search/fetch for official docs, versioned references, release notes, mig
 ### Source-Reference Evidence
 - Only if docs were insufficient; explain why
 
+### Supplemental Evidence
+- Third-party summaries, examples, or community material only when useful after official/upstream evidence; label limitations
+
 ### Caveats / Ambiguity Flags
 - Unresolved uncertainty or likely version drift
 
@@ -88,7 +93,7 @@ Use web search/fetch for official docs, versioned references, release notes, mig
 </output_contract>
 
 <scenario_handling>
-- If the user says `continue`, keep validating against official docs, version details, and source-reference evidence before finalizing.
+- If the user says `continue`, keep validating against official docs, version/date details, upstream references, and source-reference evidence before finalizing.
 - If only the output format changes, preserve the research goal and source requirements.
 </scenario_handling>
 

package/skills/autopilot/SKILL.md

@@ -1,56 +1,66 @@
 ---
 name: autopilot
-description: "[OMX] Strict autonomous loop: $ralplan -> $ralph -> $code-review"
+description: "[OMX] Strict autonomous loop: $deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa"
 ---
 
 <Purpose>
-Autopilot is the strict autonomous delivery loop for non-trivial work. Its primary contract is exactly:
+Autopilot is the strict autonomous delivery loop for non-trivial work. Its recommended/default contract is exactly:
 
 ```text
-$ralplan -> $ralph -> $code-review
+$deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa
 ```
 
-If `$code-review` is not clean, Autopilot returns to `$ralplan` with the review findings as the next planning input, then continues again through `$ralph` and `$code-review` until the review is clean or a hard blocker is reported.
+If `$code-review` or `$ultraqa` is not clean, Autopilot returns to `$ralplan` with the findings as the next planning input, then continues again through `$ultragoal`, `$code-review`, and `$ultraqa` until the gates are clean or a hard blocker is reported. Ralph is a legacy/explicit alternate execution loop only; do not advertise Ralph as the default Autopilot path.
 </Purpose>
 
 <Use_When>
-- User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed code
+- User wants hands-off execution from a concrete idea, issue, PRD, or requirements artifact to reviewed and QA-checked code
 - User says `$autopilot`, "autopilot", "auto pilot", "autonomous", "build me", "create me", "make me", "full auto", "handle it all", or "I want a/an..."
-- Task needs planning, implementation, verification, and code review with automatic follow-up when review is not clean
+- Task needs clarification, planning, durable execution, verification, code review, and QA with automatic follow-up when gates are not clean
 </Use_When>
 
 <Do_Not_Use_When>
 - User wants to explore options or brainstorm -- use `$plan` / `$ralplan`
 - User says "just explain", "draft only", or "what would you suggest" -- respond conversationally
-- User wants a single focused code change -- use `$ralph` or direct executor work
+- User wants a single focused code change -- use `$ultragoal`, `$ralph` only when explicitly requested, or direct executor work
 - User wants only review/critique of existing code -- use `$code-review`
 </Do_Not_Use_When>
 
 <Strict_Loop_Contract>
-Autopilot must not run a separate broad expansion/planning/execution/QA/validation lifecycle as its primary behavior. It delegates those concerns to the three canonical workflow phases below:
+Autopilot must not run a separate broad expansion/planning/execution/QA/validation lifecycle as its primary behavior. It delegates those concerns to the canonical workflow phases below:
 
-1. **Phase `ralplan`** — consensus planning gate
-   - Ground the task with pre-context intake.
+1. **Phase `deep-interview`** — Socratic requirements clarification gate
+   - Run or resume `$deep-interview` to clarify intent, scope, non-goals, constraints, and decision boundaries.
+   - Required handoff artifact: a clarified spec or concise requirements summary suitable for `$ralplan`.
+
+2. **Phase `ralplan`** — consensus planning gate
+   - Ground the task with pre-context intake and the deep-interview artifact.
    - Run or resume `$ralplan` to produce/update PRD and test-spec artifacts.
-   - When returning from a non-clean review, include `return_to_ralplan_reason` and the review findings as first-class planning input.
-   - Required handoff artifact: an approved plan/test spec suitable for `$ralph`.
+   - When returning from a non-clean review or QA pass, include `return_to_ralplan_reason` and the findings as first-class planning input.
+   - Required handoff artifact: an approved plan/test spec suitable for `$ultragoal`.
 
-2. **Phase `ralph`** — implementation + verification loop
-   - Run `$ralph` from the approved ralplan artifacts.
-   - Ralph owns implementation, tests, build/lint/typecheck evidence, deslop where applicable, and architect verification.
-   - Required handoff artifact: implementation evidence and changed-file summary suitable for `$code-review`.
+3. **Phase `ultragoal`** — durable implementation + verification loop
+   - Run `$ultragoal` from the approved ralplan artifacts.
+   - Ultragoal owns durable Codex goal handoffs, `.omx/ultragoal` ledger checkpoints, implementation, tests, build/lint/typecheck evidence, cleanup, and final review gate discipline.
+   - Use `$team` only inside an active Ultragoal story when the story clearly benefits from coordinated parallel execution (for example independent file/module lanes, broad test matrix work, or multi-domain implementation). Team remains explicit and leader-owned; Ultragoal keeps the goal/ledger state.
+   - Required handoff artifact: implementation evidence, changed-file summary, verification evidence, and Ultragoal ledger/checkpoint references suitable for `$code-review`.
 
-3. **Phase `code-review`** — merge-readiness gate
-   - Run `$code-review` on the diff/artifacts produced by `$ralph`.
+4. **Phase `code-review`** — merge-readiness gate
+   - Run `$code-review` on the diff/artifacts produced by `$ultragoal`.
    - A clean review means final recommendation `APPROVE` with architectural status `CLEAR`.
    - `COMMENT`, `REQUEST CHANGES`, any architectural `WATCH`/`BLOCK`, or any unresolved finding is not clean.
    - If not clean, increment the review cycle, persist `review_verdict`, set `return_to_ralplan_reason`, and transition back to Phase `ralplan`.
 
-The only normal terminal state is `complete` after a clean code review. Cancellation, blocked credentials, unrecoverable repeated failures, or explicit user stop may terminate earlier with preserved state.
+5. **Phase `ultraqa`** — adversarial QA gate
+   - Run `$ultraqa` after a clean code review when user-facing behavior, workflows, CLI/runtime behavior, integration surfaces, or regression risk warrant adversarial QA.
+   - For docs-only or trivially non-runtime changes, record `ultraqa` as skipped with an explicit condition and evidence.
+   - If UltraQA finds issues, persist the QA verdict/evidence, set `return_to_ralplan_reason`, and transition back to Phase `ralplan`.
+
+The only normal terminal state is `complete` after clean code review and a passed or explicitly skipped UltraQA gate. Cancellation, blocked credentials, unrecoverable repeated failures, or explicit user stop may terminate earlier with preserved state.
 </Strict_Loop_Contract>
 
 <Pre-context Intake>
-Before Phase `ralplan` starts or resumes:
+Before Phase `deep-interview` or `ralplan` starts or resumes:
 1. Derive a task slug from the request.
 2. Reuse the latest relevant `.omx/context/{slug}-*.md` snapshot when available.
 3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
@@ -60,16 +70,18 @@ Before Phase `ralplan` starts or resumes:
    - constraints
    - unknowns/open questions
    - likely codebase touchpoints
-4. If ambiguity remains high, run `explore` first for brownfield facts, then run the Socratic `$deep-interview --quick <task>` before `$ralplan`.
+4. If brownfield facts are missing, run `explore` first before or during `$deep-interview` (`$deep-interview --quick <task>` remains acceptable for bounded low-ambiguity intake); do not skip the clarification gate merely because the task sounds actionable.
 5. Carry the snapshot path in Autopilot state and all handoff artifacts.
 </Pre-context Intake>
 
 <Execution_Policy>
-- Always execute phases in order: `ralplan`, then `ralph`, then `code-review`.
-- Never skip directly from vague/freeform expansion to implementation; unclear input must be clarified or planned through `$ralplan`.
-- A non-clean `$code-review` always returns to `$ralplan`; do not patch findings ad hoc outside the loop.
+- Always execute the recommended phases in order: `deep-interview`, then `ralplan`, then `ultragoal`, then `code-review`, then `ultraqa`.
+- `$team` is conditional and explicit: use it only within an Ultragoal story when parallel execution materially improves throughput, quality, or safety.
+- Never skip directly from vague/freeform expansion to implementation; unclear input must be clarified and planned through `$deep-interview` and `$ralplan`.
+- A non-clean `$code-review` or failed `$ultraqa` always returns to `$ralplan`; do not patch findings ad hoc outside the loop.
 - Each phase must write/update Autopilot state before handing off.
-- Use existing hooks, `.omx/state`, `$ralplan`, `$ralph`, `$code-review`, and pipeline primitives; do not invent a separate execution framework.
+- Use existing hooks, `.omx/state`, `$deep-interview`, `$ralplan`, `$ultragoal`, optional `$team`, `$code-review`, `$ultraqa`, and pipeline primitives; do not invent a separate execution framework.
+- Preserve legacy compatibility: if a user explicitly requests the old Ralph execution lane, use `$ralph` as an intentional alternate execution phase, but do not present it as Autopilot's default recommended loop.
 - Continue automatically through safe reversible phase transitions. Ask only for destructive, credential-gated, or materially preference-dependent branches.
 - Apply the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step execution, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.
 </Execution_Policy>
@@ -83,81 +95,99 @@ Required fields:
 {
   "mode": "autopilot",
   "active": true,
-  "current_phase": "ralplan",
+  "current_phase": "deep-interview",
   "iteration": 1,
   "review_cycle": 0,
   "max_iterations": 10,
-  "phase_cycle": ["ralplan", "ralph", "code-review"],
+  "phase_cycle": ["deep-interview", "ralplan", "ultragoal", "code-review", "ultraqa"],
   "handoff_artifacts": {
     "context_snapshot_path": ".omx/context/<slug>-<timestamp>.md",
+    "deep_interview": null,
     "ralplan": null,
-    "ralph": null,
-    "code_review": null
+    "ultragoal": null,
+    "code_review": null,
+    "ultraqa": null
   },
   "review_verdict": null,
+  "qa_verdict": null,
   "return_to_ralplan_reason": null
 }
 ```
 
-- **On start**: `omx state write --input '{"mode":"autopilot","active":true,"current_phase":"ralplan","iteration":1,"review_cycle":0,"state":{"phase_cycle":["ralplan","ralph","code-review"],"handoff_artifacts":{"context_snapshot_path":"<snapshot-path>","ralplan":null,"ralph":null,"code_review":null},"review_verdict":null,"return_to_ralplan_reason":null}}' --json`
-- **On ralplan -> ralph**: set `current_phase:"ralph"`, persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
-- **On ralph -> code-review**: set `current_phase:"code-review"`, persist implementation/test evidence under `handoff_artifacts.ralph`.
-- **On clean review**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}` and `completed_at`.
-- **On non-clean review**: increment `iteration` and `review_cycle`, set `current_phase:"ralplan"`, persist `review_verdict:{..., clean:false}`, persist `handoff_artifacts.code_review`, and set `return_to_ralplan_reason` to a concise review-driven reason.
+- **On start**: `omx state write --input '{"mode":"autopilot","active":true,"current_phase":"deep-interview","iteration":1,"review_cycle":0,"state":{"phase_cycle":["deep-interview","ralplan","ultragoal","code-review","ultraqa"],"handoff_artifacts":{"context_snapshot_path":"<snapshot-path>","deep_interview":null,"ralplan":null,"ultragoal":null,"code_review":null,"ultraqa":null},"review_verdict":null,"qa_verdict":null,"return_to_ralplan_reason":null}}' --json`
+- **On deep-interview -> ralplan**: set `current_phase:"ralplan"`, persist the clarified spec/requirements under `handoff_artifacts.deep_interview`.
+- **On ralplan -> ultragoal**: set `current_phase:"ultragoal"`, persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
+- **On ultragoal -> code-review**: set `current_phase:"code-review"`, persist implementation/test/ledger evidence under `handoff_artifacts.ultragoal`.
+- **On code-review -> ultraqa**: set `current_phase:"ultraqa"`, persist the clean review under `handoff_artifacts.code_review`.
+- **On clean review + passed/skipped QA**: set `active:false`, `current_phase:"complete"`, persist `review_verdict:{recommendation:"APPROVE", architectural_status:"CLEAR", clean:true}`, `qa_verdict:{clean:true, skipped:<boolean>, reason:<string|null>}`, and `completed_at`.
+- **On non-clean review or failed QA**: increment `iteration` and `review_cycle`, set `current_phase:"ralplan"`, persist `review_verdict` or `qa_verdict`, persist the phase handoff, and set `return_to_ralplan_reason` to a concise findings-driven reason.
+- **Legacy Ralph state**: if a user explicitly selected the legacy Ralph execution lane, phase names and handoff keys may include `ralph`; preserve and resume them rather than rewriting history to Ultragoal.
 - **On cancellation**: run `$cancel`; preserve progress for resume rather than deleting handoff artifacts.
 </State_Management>
 
 <Continuation_And_Resume>
 When the user says `continue`, `resume`, or `keep going` while Autopilot is active, read `autopilot-state.json` and continue from `current_phase`:
+- `deep-interview`: clarify requirements and record the handoff artifact.
 - `ralplan`: run/update consensus planning from current handoffs and any `return_to_ralplan_reason`.
-- `ralph`: execute the approved plan and record verification evidence.
+- `ultragoal`: execute the approved plan durably and record verification/ledger evidence.
+- `team`: continue explicit team work only when it is nested under the active Ultragoal story and report evidence back to the leader.
 - `code-review`: review the current diff and decide clean vs return-to-ralplan.
+- `ultraqa`: run or explicitly skip adversarial QA based on the documented condition, then finish if clean or transition to `ralplan` with findings if not clean.
+- `ralph`: resume only for explicit legacy Ralph-path Autopilot state.
 - `complete`: report completion evidence; do not restart.
 
 Do not restart discovery or discard handoff artifacts on continuation.
 </Continuation_And_Resume>
 
 <Pipeline_Orchestrator>
-Autopilot may be represented by the configurable pipeline orchestrator (`src/pipeline/`) when useful. The Autopilot pipeline contract is:
+Autopilot may be represented by the configurable pipeline orchestrator (`src/pipeline/`) when useful. The default Autopilot pipeline contract is:
 
 ```text
-ralplan -> ralph -> code-review
+deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa
 ```
 
-Pipeline state should use `current_phase` values that match the same phase names (`ralplan`, `ralph`, `code-review`, `complete`, `failed`) and should carry `iteration`, `review_cycle`, `handoff_artifacts`, `review_verdict`, and `return_to_ralplan_reason` alongside stage results.
+Pipeline state should use `current_phase` values that match the same phase names (`deep-interview`, `ralplan`, `ultragoal`, `code-review`, `ultraqa`, `complete`, `failed`) and should carry `iteration`, `review_cycle`, `handoff_artifacts`, `review_verdict`, `qa_verdict`, and `return_to_ralplan_reason` alongside stage results. `$team` is not a default pipeline stage; it is an explicit conditional execution engine inside an Ultragoal story.
 </Pipeline_Orchestrator>
 
 <Escalation_And_Stop_Conditions>
 - Stop and report a blocker when required credentials/authority are missing.
-- Stop and report when the same review or verification failure recurs across 3 review cycles with no meaningful new plan.
+- Stop and report when the same review or QA failure recurs across 3 review cycles with no meaningful new plan.
 - Stop when the user says "stop", "cancel", or "abort" and run `$cancel`.
-- Otherwise, continue the loop until `$code-review` is clean.
+- Otherwise, continue the loop until `$code-review` is clean and `$ultraqa` has passed or been explicitly skipped with evidence.
 </Escalation_And_Stop_Conditions>
 
 <Final_Checklist>
+- [ ] Phase `deep-interview` produced/updated clarified requirements or a concise spec
 - [ ] Phase `ralplan` produced/updated approved planning artifacts
-- [ ] Phase `ralph` implemented and verified the plan with fresh evidence
+- [ ] Phase `ultragoal` implemented and verified the plan with fresh evidence and durable ledger/checkpoint references
+- [ ] `$team` was used only if the active Ultragoal story needed coordinated parallel work, or explicitly recorded as not needed
 - [ ] Phase `code-review` returned a clean verdict (`APPROVE` + `CLEAR`)
-- [ ] `review_verdict.clean` is true and `return_to_ralplan_reason` is null
-- [ ] Tests/build/lint/typecheck evidence from Ralph is available in handoff artifacts
+- [ ] Phase `ultraqa` passed, or was explicitly skipped because the change was docs-only/trivially non-runtime with evidence
+- [ ] `review_verdict.clean` is true, `qa_verdict.clean` is true, and `return_to_ralplan_reason` is null
+- [ ] Tests/build/lint/typecheck evidence from Ultragoal is available in handoff artifacts
 - [ ] Autopilot state is marked `complete` or cancellation state is preserved coherently
-- [ ] User receives a concise summary with plan, implementation, verification, and review evidence
+- [ ] User receives a concise summary with clarification, plan, implementation, verification, review, and QA evidence
 </Final_Checklist>
 
 <Examples>
 <Good>
 User: `$autopilot implement GitHub issue #42`
-Flow: create/load context snapshot -> `$ralplan` issue plan -> `$ralph` implementation + tests -> `$code-review`; if review requests changes, return to `$ralplan` with findings.
+Flow: create/load context snapshot -> `$deep-interview` requirements check -> `$ralplan` issue plan -> `$ultragoal` durable implementation + tests (launch `$team` only if a story needs parallel lanes) -> `$code-review` -> `$ultraqa`; if review or QA requests changes, return to `$ralplan` with findings.
 </Good>
 
 <Good>
 User: `continue`
 Context: Autopilot state says `current_phase:"code-review"`.
-Flow: run `$code-review` on current diff, persist verdict, finish if clean or transition to `ralplan` with findings if not clean.
+Flow: run `$code-review` on current diff, persist verdict, transition to `ultraqa` if clean or to `ralplan` with findings if not clean.
+</Good>
+
+<Good>
+User: `$autopilot --legacy-ralph finish the migration`
+Flow: preserve the explicit legacy Ralph execution choice and run the old Ralph execution lane as an alternate, without changing the documented default Autopilot recommendation.
 </Good>
 
 <Bad>
 Autopilot invents independent "Expansion", "QA", and "Validation" phases and treats them as the primary lifecycle.
-Why bad: this bypasses the strict `$ralplan -> $ralph -> $code-review` contract.
+Why bad: this bypasses the strict `$deep-interview -> $ralplan -> $ultragoal -> $code-review -> $ultraqa` contract.
 </Bad>
 </Examples>