oh-my-codex 0.20.5 → 0.21.0

package/skills/autopilot/SKILL.md

@@ -1,105 +1,49 @@
 ---
 name: autopilot
-description: "[OMX] Strict autonomous loop: $deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa"
+description: "[OMX] Canonical autonomous orchestrator: $deep-interview -> $ralplan -> $ultragoal"
 ---
 
+# Autopilot
+
 <Purpose>
-Autopilot is the strict autonomous delivery loop for non-trivial work. Its recommended/default contract is exactly:
+Autopilot is the first-class canonical orchestrator for hands-off delivery. Its defining default chain is mandatory:
 
 ```text
-$deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa
+$deep-interview -> $ralplan -> $ultragoal
 ```
 
-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.
+The chain is not a list of optional hints and Autopilot is not an alias for direct execution. Autopilot supervises each child stage in one recoverable session, carries durable artifacts forward, and continues through implementation verification until the requested outcome is complete or a genuine blocker is recorded.
 </Purpose>
 
 <Use_When>
-- 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 clarification, planning, durable execution, verification, code review, and QA with automatic follow-up when gates are not clean
+- The user explicitly invokes `$autopilot`.
+- The user asks for end-to-end autonomous delivery from an idea, issue, or requirements seed.
+- The work needs requirements clarification, consensus planning, durable execution, and evidence-backed completion as one supervised workflow.
 </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 `$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 canonical workflow phases below:
-
-1. **Phase `deep-interview`** — Socratic requirements clarification gate
-   - Run or resume `$deep-interview` to clarify intent, scope, non-goals, constraints, and decision boundaries.
-   - Deep-interview is a structured question chain, not a one-question gate; `max_rounds` is a cap, not a target.
-   - After a user answers an `omx question`, re-score ambiguity against the active profile threshold. Ask another question only when a readiness gate is still unresolved and the answer would materially change execution; otherwise crystallize the spec and hand off.
-   - Required handoff artifact: a clarified spec or concise requirements summary suitable for `$ralplan`, including an explicit interview-complete rationale when leaving deep-interview.
-
-2. **Phase `ralplan`** — consensus planning gate
-   - Ground the task with pre-context intake and the deep-interview artifact.
-   - Current ownership rule: Autopilot records `planning_routing` in state before heavy planning. When the Autopilot/main model resolves to a cheap/mini lane (for example `o4-mini`, `*-mini`, `*spark*`, or an explicitly cheap/economy/lite model name), the initial planning/decomposition owner is dedicated `[planner]`; otherwise `[main]` may keep ownership for backward compatibility. A configured `agentModels.planner` is an explicit opt-in that forces dedicated `[planner]` ownership even when `[main]` is not cheap/mini.
-   - Run or resume `$ralplan` to produce/update PRD and test-spec artifacts. If `planning_routing.owner` is `planner`, use the dedicated `[planner]` role for the initial Planner draft/decomposition before the Architect→Critic consensus gates.
-   - PRD/test-spec files alone are not completion evidence. Local Architect→Critic approvals are lifecycle evidence, not handoff authority. Ralplan may hand off only after an official host-issued receipt is verified through a documented non-user-mintable host surface; until then retain the reviews with `ralplan_consensus_gate.complete:false` and `blocked_reason:"documented_host_consensus_receipt_unavailable"`.
-   - On every revised planning pass, require subsequent `Architect` approval first and subsequent `Critic` approval second. These ordered reviews remain lifecycle evidence only and never replace the official host receipt.
-   - When returning from a non-clean review or QA pass, include `return_to_ralplan_reason` and the findings as first-class planning input.
-   - If either review is missing, blocked, out of order, or non-approving, remain in `ralplan` or report an explicit blocker/max-iteration outcome; do not progress to `$ultragoal`, `$team`, `$ralph`, or implementation.
-   - Required handoff artifact: planning artifacts, lifecycle-only Architect→Critic reviews, and a verified official host receipt authorizing `ralplan_consensus_gate.complete:true`. Without that receipt, remain in `ralplan` and report the host blocker.
-
-3. **Phase `ultragoal`** — durable implementation + verification loop
-   - Run `$ultragoal` only from ralplan artifacts whose consensus gate is authorized by a verified official host receipt.
-   - 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`.
-
-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 because the implementation must be repaired, increment the review cycle, persist `review_verdict`, set `current_phase:"rework"`, and carry the findings as the sanctioned execution-fix input. Return to Phase `ralplan` only when the review shows the plan/requirements are wrong or incomplete.
-
-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 `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:
-   - activation prompt / task seed
-   - original task status (`activation-prompt`, `legacy-unverified`, or `unavailable`)
-   - desired outcome
-   - known facts/evidence
-   - constraints
-   - unknowns/open questions
-   - likely codebase touchpoints
-   - a scope note that the seed is the Autopilot activation prompt, not guaranteed prior conversation context
-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>
+<Default_Chain>
+Run or resume these stages in order:
+
+1. **`deep-interview`** — clarify intent, scope, non-goals, constraints, acceptance criteria, and unresolved decisions. Produce a durable requirements/specification handoff. Deep Interview is a real stage; do not replace it with a one-question check or skip it merely because the task looks actionable.
+2. **`ralplan`** — turn the clarified requirements into an execution-ready consensus plan with architecture, sequencing, test, and verification guidance. Preserve review evidence as lifecycle evidence, not host-issued security authority.
+3. **`ultragoal`** — execute the approved plan through durable goals and ledger receipts, implementation, focused verification, cleanup, review, and terminal evidence.
+
+`$team`, `$code-review`, and `$ultraqa` may be used inside the supervised execution when the active Ultragoal plan or verification boundary requires them. They do not replace or weaken the defining three-stage chain.
+
+When review or QA proves the requirements or plan wrong, keep Autopilot active, return its supervised phase to `ralplan`, attach the findings, and continue through `ultragoal` again. Implementation-only review fixes may remain within Ultragoal's blocker/review loop.
+</Default_Chain>
 
 <Execution_Policy>
-- 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` that requires implementation repair enters Phase `rework`; a non-clean review that changes the plan/requirements, or failed `$ultraqa`, returns to `$ralplan`.
-- Each phase must write/update Autopilot state before handing off.
-- 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.
+- Autopilot MUST begin at `deep-interview` for a new run and MUST preserve the phase order `deep-interview -> ralplan -> ultragoal`.
+- Child stages are supervised phases, not peer workflow activations. Keep `mode:"autopilot"` active and update `current_phase` rather than replacing Autopilot with standalone child state.
+- Use the current CLI state SSOT (`omx state ... --json`) and the current session-scoped state root. Do not create a second writer or revive legacy root-state authority.
+- Local artifacts, prompts, trackers, transcripts, environment values, and role labels are lifecycle evidence only. Do not reintroduce the retired unrecoverable host-receipt lock or terminalize the workflow because host provenance is unavailable.
+- Authority-decreasing operations are always recoverable: `$cancel`, state clear, hook disable/uninstall recovery, and stale-state repair must remain available without completion receipts or child-stage approval.
+- Continue automatically through safe, reversible stage transitions. Stop only for an explicit user cancellation, a human-only dependency, or a verified terminal result.
 </Execution_Policy>
 
 <State_Management>
-Use the CLI-first state surface (`omx state ... --json`) for Autopilot lifecycle state. State must be session-aware when a session id exists. If the explicit MCP compatibility surface is already available, equivalent `omx_state` tool calls remain acceptable but are not required.
-
-Inside active Autopilot, named child phases such as `$ralplan` are supervised phases, not peer workflow activations: keep `mode:"autopilot"` active and update `current_phase:"ralplan"` rather than starting standalone `mode:"ralplan"` over Autopilot.
-
-Required fields:
+Autopilot state is session-scoped and owned by the canonical state writer. A new run records at least:
 
 ```json
 {
@@ -107,121 +51,78 @@ Required fields:
   "active": true,
   "current_phase": "deep-interview",
   "iteration": 1,
-  "review_cycle": 0,
-  "max_iterations": 10,
-  "phase_cycle": ["deep-interview", "ralplan", "ultragoal", "code-review", "ultraqa"],
+  "phase_cycle": ["deep-interview", "ralplan", "ultragoal"],
   "handoff_artifacts": {
-    "context_snapshot_path": ".omx/context/<slug>-<timestamp>.md",
     "deep_interview": null,
     "ralplan": null,
-    "ralplan_consensus_gate": {
-      "required": true,
-      "sequence": ["architect-review", "critic-review"],
-      "planning_artifacts_are_not_consensus": true,
-      "required_review_roles": ["architect", "critic"],
-      "ralplan_architect_review": null,
-      "ralplan_critic_review": null,
-      "complete": false
-    },
-    "ultragoal": null,
-    "code_review": null,
-    "ultraqa": null
+    "ultragoal": null
   },
-  "review_verdict": null,
-  "qa_verdict": null,
   "return_to_ralplan_reason": null
 }
 ```
 
-- **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,"ralplan_consensus_gate":{"required":true,"sequence":["architect-review","critic-review"],"planning_artifacts_are_not_consensus":true,"required_review_roles":["architect","critic"],"ralplan_architect_review":null,"ralplan_critic_review":null,"complete":false},"ultragoal":null,"code_review":null,"ultraqa":null},"review_verdict":null,"qa_verdict":null,"return_to_ralplan_reason":null}}' --json`
-- **On deep-interview -> ralplan**: only after a separate gate proves the interview chain is explicitly complete or the user explicitly authorized a skip. For completion, persist `deep_interview_gate:{"status":"complete","rationale":"<why requirements are complete>","handoff_summary":"<summary>"}` (or equivalent non-empty rationale/summary) plus the clarified spec/requirements under `handoff_artifacts.deep_interview`; if a final `omx question` was involved, keep its same-session answered record linked by `question_id`/`satisfied_at`. For skip, persist `deep_interview_gate:{"status":"skipped","skip_authorized_by_user":true,"skip_reason":"<user-authorized reason>","skipped_at":"<timestamp>","source":"user","session_id":"<session>"}`. Do not leave deep-interview merely because the first `omx question` was answered or cleared.
-  - The stable `<!-- OMX:AUTOPILOT:DEEP-INTERVIEW-RALPLAN-HANDOFF:v1 -->` marker immediately precedes the executable completion handoff fence; automation may locate exactly that fence.
+Start or update state only through the CLI-first state surface:
 
-<!-- OMX:AUTOPILOT:DEEP-INTERVIEW-RALPLAN-HANDOFF:v1 -->
 ```bash
-omx state write --input '{"mode":"autopilot","active":true,"current_phase":"ralplan","session_id":"'"${OMX_SESSION_ID:?authoritative OMX session required}"'","workingDirectory":"'"${PWD:?working directory required}"'","state":{"deep_interview_gate":{"status":"complete","rationale":"requirements are clarified and ready for planning","handoff_summary":"durable deep-interview handoff recorded for ralplan"},"handoff_artifacts":{"deep_interview":".omx/specs/deep-interview-handoff.md"}}}' --json
+omx state write --input '{"mode":"autopilot","active":true,"current_phase":"deep-interview","state":{"phase_cycle":["deep-interview","ralplan","ultragoal"],"handoff_artifacts":{"deep_interview":null,"ralplan":null,"ultragoal":null},"return_to_ralplan_reason":null}}' --json
 ```
-  - The artifact path above must already contain the durable clarified requirements/specification before this command runs. Omit session aliases unless needed; if emitted, `owner_omx_session_id`, `codex_session_id`, and `owner_codex_session_id` must each equal `session_id`.
-  - **Optional execution contract foundation**: when a downstream handoff explicitly sets `execution_contract_required:true`, persist a complete structured `execution_contract` under `handoff_artifacts.deep_interview` before leaving deep-interview. The canonical schema is `version:1`, `execution_stride:"task"|"deliverable"|"milestone"`, `source:"deep-interview"`, `selected_by:"user"|"default"`, `allow_task_shrink:<boolean>`, non-empty `completion_unit`, non-empty `stop_condition`, `acceptance_coverage_scope:"task"|"deliverable"|"milestone"`, and `shrink_policy:"allowed"|"ask_before_shrink"|"deny_unless_blocked"`.
-  - Stride semantics are binding only when `execution_contract_required:true`: `task` means `allow_task_shrink:true`, `acceptance_coverage_scope:"task"`, `shrink_policy:"allowed"`; `deliverable` means `allow_task_shrink:false`, `acceptance_coverage_scope:"deliverable"`, `shrink_policy:"ask_before_shrink"`; `milestone` means `allow_task_shrink:false`, `acceptance_coverage_scope:"milestone"`, `shrink_policy:"deny_unless_blocked"`.
-  - Preserve legacy behavior when `execution_contract_required` is absent or false. Do not infer stride from prose, broadness, phase names, snapshots, or task size; this foundation only validates an explicit structured contract and deliberately uses `milestone` rather than `phase`. New artifacts must write canonical snake_case keys under `handoff_artifacts.deep_interview`; the runtime may read legacy camelCase field/marker aliases and direct/nested `execution_contract` locations only as compatibility input.
-- **On ralplan -> ultragoal**: only after `ralplan_consensus_gate.complete:true` from an official host-issued receipt verified through a documented non-user-mintable host surface. Native-subagent Architect/Critic lanes, tracker records, `codex_exec`, and artifact approvals are lifecycle or trace evidence only. Until that verifier exists, keep `current_phase:"ralplan"` and persist `blocked_reason:"documented_host_consensus_receipt_unavailable"`.
-- **On missing ralplan consensus evidence**: keep `current_phase:"ralplan"`, persist `ralplan_consensus_gate.complete:false` with `blocked_reason`, and report an explicit blocker or max-iteration outcome instead of handing off to execution.
-- **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"` only after a real `$code-review` stage/subagent has produced durable evidence; persist the clean review under `handoff_artifacts.code_review` with its source thread/tool/stage reference. Do not author `review_verdict:{clean:true}` from the leader's own summary.
-- **On non-clean code-review requiring implementation repair**: increment `review_cycle`, set `current_phase:"rework"`, persist `review_verdict`, persist the phase handoff under `handoff_artifacts.code_review`, and keep the fix scoped to the review findings before returning to `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` only when both gates have durable source evidence. Required evidence is either (a) actual `$code-review`/`$ultraqa` stage or native-subagent/thread/tool records, or (b) for QA only, an explicit persisted skip reason for a documented docs-only/trivially non-runtime condition. If that evidence is missing, keep the active phase at `code-review` or `ultraqa` and record a blocker instead of self-attesting a clean gate.
-- **On non-clean review requiring plan changes 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.
+
+Stage transitions:
+
+- **`deep-interview -> ralplan`**: require a durable clarified requirements/specification artifact and a non-empty completion rationale. Preserve same-session question evidence when a question surface was used.
+- **`ralplan -> ultragoal`**: require durable planning artifacts, sequential Architect then Critic approvals, and a session/review-cycle-bound `ralplan_execution_handoff`. For supervised Autopilot, the explicit Autopilot request is the source of that bound handoff. Ordinary progression MUST NOT depend on a host-issued consensus receipt; missing host provenance is not a blocker.
+- **`ultragoal -> complete`**: require durable goal/ledger completion receipts and fresh verification evidence matching the requested outcome.
+- **review/QA loopback**: keep Autopilot active, set `current_phase:"ralplan"`, and persist `return_to_ralplan_reason` plus the findings.
+- **cancellation**: run `$cancel`; preserve handoff artifacts for inspection or resume and mark the exact session terminal without deleting unrelated state.
+- **clear/recovery**: exact-session clear may remove corrupt or stale Autopilot state. It must not require forward-progression evidence and must not clear other skills or sessions.
 </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`.
-- `ultragoal`: execute the approved plan durably and record verification/ledger evidence.
-- `rework`: perform only the implementation fixes required by the current code-review findings, record fresh implementation/verification evidence, and return to `code-review`.
-- `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>
+When the user says `continue`, `resume`, or `keep going`, read the current session's `autopilot-state.json` and continue from `current_phase`:
 
-<Pipeline_Orchestrator>
-Autopilot may be represented by the configurable pipeline orchestrator (`src/pipeline/`) when useful. The default Autopilot pipeline contract is:
+- `deep-interview`: resume clarification and produce the requirements handoff.
+- `ralplan`: resume consensus planning from the deep-interview artifact and any loopback findings.
+- `ultragoal`: resume durable execution from the approved plan and ledger.
+- `complete`: report the terminal evidence; do not restart.
+- `cancelled`, `cleared`, or `failed`: report preserved artifacts and start a new run only on a new explicit Autopilot request.
 
-```text
-deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa
-```
+Never discard valid handoff artifacts or restart discovery merely because the conversation resumed.
+</Continuation_And_Resume>
 
-Pipeline state should use `current_phase` values that match the same phase names (`deep-interview`, `ralplan`, `ultragoal`, `rework`, `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>
+<Recovery_Contract>
+Autopilot continuation hooks may nudge an active non-terminal run, but they MUST fail open for recovery:
 
-<Escalation_And_Stop_Conditions>
-- Stop and report a blocker when required credentials/authority are missing.
-- 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 and `$ultraqa` has passed or been explicitly skipped with evidence.
-</Escalation_And_Stop_Conditions>
+- A stale, malformed, cancelled, cleared, complete, or foreign-session state must not keep Stop blocked.
+- `$cancel`, exact-session state clear, and setup hook disable/uninstall paths must remain executable while Autopilot is active or damaged.
+- Continuation must be bounded and session-scoped; never recreate an unconditional hook lock.
+</Recovery_Contract>
 
 <Final_Checklist>
-- [ ] Phase `deep-interview` produced/updated clarified requirements or a concise spec
-- [ ] Phase `ralplan` produced/updated planning artifacts and preserved subsequent Architect→Critic approvals as lifecycle-only evidence; it advanced only with a verified official host receipt, or remained in `ralplan` with `complete:false` and `blocked_reason:"documented_host_consensus_receipt_unavailable"`.
-- [ ] Phase `ultragoal` implemented and verified the plan with fresh evidence and durable ledger/checkpoint references
-- [ ] Phase `rework` was used for implementation-only review fixes when applicable, with findings scoped to a fresh code-review cycle
-- [ ] `$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`)
-- [ ] Phase `ultraqa` passed, or was explicitly skipped because the change was docs-only/trivially non-runtime with evidence
-- [ ] Clean `review_verdict` cites durable source evidence from a real `$code-review` stage/subagent/thread/tool record; `qa_verdict` cites durable `$ultraqa` evidence or an explicit persisted low-risk skip reason; leader-authored summaries alone are not gate 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 clarification, plan, implementation, verification, review, and QA evidence
+- [ ] A new run started with `deep-interview`.
+- [ ] Deep Interview produced a durable clarified requirements/specification handoff.
+- [ ] Ralplan produced an execution-ready plan with lifecycle review evidence.
+- [ ] Ultragoal completed the plan with durable goals and ledger receipts.
+- [ ] Verification evidence covers the requested behavior, failure paths, and recovery paths.
+- [ ] Missing host provenance did not block ordinary progression, cancel, clear, or hook recovery.
+- [ ] Autopilot state is terminal and exact-session artifacts remain coherent.
 </Final_Checklist>
 
 <Examples>
 <Good>
-User: `$autopilot implement GitHub issue #42`
-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.
+User: `$autopilot implement issue #42`
+Flow: activate Autopilot at `deep-interview`, crystallize requirements, continue to supervised `ralplan`, then supervised `ultragoal`, verify the completed outcome, and mark the exact session complete.
 </Good>
 
 <Good>
 User: `continue`
-Context: Autopilot state says `current_phase:"code-review"`.
-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.
+Context: Autopilot state has `current_phase:"ralplan"`.
+Flow: resume the existing plan from the deep-interview handoff; do not create a separate standalone Ralplan run.
 </Good>
 
 <Bad>
-Autopilot invents independent "Expansion", "QA", and "Validation" phases and treats them as the primary lifecycle.
-Why bad: this bypasses the strict `$deep-interview -> $ralplan -> $ultragoal -> $code-review -> $ultraqa` contract.
+Flow: treat `$deep-interview`, `$ralplan`, and `$ultragoal` as optional suggestions and jump directly to implementation.
+Why bad: this hollows out Autopilot's defining orchestration contract.
 </Bad>
 </Examples>
+
+Task: {{ARGUMENTS}}

package/skills/autoresearch-goal/SKILL.md

@@ -1,39 +1,14 @@
 ---
 name: autoresearch-goal
-description: Durable professor-critic research workflow over Codex goal mode without reviving deprecated omx autoresearch
+description: Sunset stub — use $autoresearch instead
 ---
 
-# Autoresearch Goal
+# Autoresearch-goal — removed
 
-Use this workflow when a research mission should be bound to Codex goal-mode focus while OMX remains the durable state owner. This is for research projects that need Codex goal-mode management plus professor/critic-style validation; it is not the default answer for ordinary pre-planning best-practice lookup.
+`$autoresearch-goal` was removed in OMX 0.21; use `$autoresearch` instead.
 
-## Boundary
-- Do **not** use or revive the deprecated `omx autoresearch` direct launch surface.
-- Do **not** claim shell commands mutate hidden Codex `/goal` state.
-- Do **not** edit upstream `../../codex` or add dependencies.
-- Use `get_goal`, `create_goal`, and `update_goal({status: "complete"})` only through the active Codex thread when those tools are available.
+Autoresearch-goal was a duplicate research-over-goal-mode entry point. `$autoresearch` is the single canonical validator-gated research loop; it owns the research mission lifecycle that autoresearch-goal duplicated.
 
-## Artifacts
-`omx autoresearch-goal` writes:
-- `.omx/goals/autoresearch/<slug>/mission.json`
-- `.omx/goals/autoresearch/<slug>/rubric.md`
-- `.omx/goals/autoresearch/<slug>/ledger.jsonl`
-- `.omx/goals/autoresearch/<slug>/completion.json`
+Migration: replace `$autoresearch-goal` with `$autoresearch`.
 
-## Flow
-1. Create the mission and professor-critic rubric:
-   `omx autoresearch-goal create --topic "..." --rubric "..." --critic-command "..."`
-2. Emit the model-facing handoff:
-   `omx autoresearch-goal handoff --slug <slug>`
-3. In the active Codex thread, call `get_goal`; call `create_goal` only if no active goal exists and the printed payload is the intended objective.
-4. Research iteratively against the rubric. Record every critic outcome:
-   `omx autoresearch-goal verdict --slug <slug> --verdict <pass|fail|blocked> --evidence "..."`
-5. Completion is blocked until professor-critic validation records `verdict=pass`. After the mission audit passes, call `update_goal({status: "complete"})`, call `get_goal` again, then run:
-   `omx autoresearch-goal complete --slug <slug> --codex-goal-json <get_goal-json-or-path>`
-6. Treat the completion command as read-only reconciliation plus durable OMX state update; hooks and shell commands must not mutate Codex goal state.
-7. After the completion command succeeds, run `/goal clear` in the Codex UI before starting another goal in this same thread/session. OMX prints this terminal cleanup step but does not invoke hidden clear routes.
-
-## Completion gate
-A passing professor-critic artifact and a matching complete Codex `get_goal` snapshot are required. Assistant prose, partial tests, or a failed/blocked verdict are not sufficient.
-
-Lifecycle: `create_goal` starts the Codex thread goal, `update_goal({status: "complete"})` marks terminal success after the professor-critic and audit pass, and `/goal clear` removes the completed thread goal when another same-thread goal is needed. OMX shell commands and hooks reconcile snapshots and print the cleanup instruction; they must not mutate hidden Codex goal state.
+Task: {{ARGUMENTS}}