oh-my-codex-pennix 0.18.13

package/skills/ai-slop-cleaner/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: ai-slop-cleaner
+description: Run an anti-slop cleanup/refactor/deslop workflow
+---
+
+# AI Slop Cleaner Skill
+
+Reduce AI-generated slop with a regression-tests-first, smell-by-smell cleanup workflow that preserves behavior and raises signal quality.
+
+## When to Use
+
+Use this skill when:
+- A code path works but feels bloated, noisy, repetitive, or over-abstracted
+- A user asks to “cleanup”, “refactor”, or “deslop” AI-generated output
+- Follow-up implementation left duplicate code, dead code, weak boundaries, missing tests, fallback-like code, or unnecessary wrapper layers
+- You need a disciplined cleanup workflow without broad rewrites
+
+## GPT-5.5 Guidance Alignment
+
+- Keep outputs concise and evidence-dense unless risk or the user requests more detail.
+- Treat newer user instructions as local workflow updates without discarding earlier non-conflicting constraints.
+- Keep using inspection, tests, diagnostics, and verification until the cleanup is grounded.
+- Proceed automatically through clear, reversible cleanup steps; ask only when a choice materially changes scope or behavior.
+
+## Scoped File Lists and Ralph Workflow
+
+- This skill can accept a **file list scope** instead of a whole feature area.
+- When the caller provides a changed-files list (for example, Ralph session-owned edits), keep the cleanup strictly bounded to those files.
+- In the **Ralph workflow**, the mandatory deslop pass should run this skill on Ralph's changed files only, in standard mode unless the caller explicitly requests otherwise.
+
+## Procedure
+
+1. **Lock behavior with regression tests first**
+   - Identify the behavior that must not change
+   - Add or run targeted regression tests before editing cleanup candidates
+   - If behavior is currently untested, create the narrowest test coverage needed first
+   - For fallback-like code, cover the primary path and any preserved compatibility/fail-safe fallback before cleanup
+
+2. **Create a cleanup plan before code**
+   - List the specific smells to remove
+   - Bound the pass to the requested files/scope
+   - If a file list scope is provided, keep the pass restricted to that changed-files list
+   - Include fallback findings, classifications, and escalation status in the plan
+   - Order fixes from safest/highest-signal to riskiest
+   - Do not start coding until the cleanup plan is explicit
+
+3. **Inventory fallback-like code before editing**
+   - Search the requested scope for fallback-like detection signals: quick hacks, temporary workaround, temporary fallback, just bypass, just skip, fallback if it fails, swallowed errors, silent defaults, broad compatibility shims, and duplicate alternate execution paths
+   - Classify each finding before changing it:
+     - **Masking fallback slop** — hides errors or evidence, bypasses the primary contract, suppresses tests or validation, swallows failures, silently defaults, or adds untested alternate paths
+     - **Grounded compatibility/fail-safe fallback** — is scoped to an external/version/fail-safe boundary, documents the rationale, preserves failure evidence, and has regression tests for both the primary and fallback behavior
+   - Prefer root-cause repair, deletion, boundary repair, or explicit failure behavior before preserving fallback paths
+   - For broad, ambiguous, cross-layer, or architectural fallback-like code, invoke `$ralplan` for consensus resolution before edits
+   - Recursion guard: when already inside ralplan, ralph, team, or another OMX workflow, do not spawn a nested `$ralplan`; record the finding and attach it to the active ralplan, leader, or plan handoff instead
+
+4. **Categorize issues before editing**
+   - **Fallback-like code** — masking fallbacks, workaround branches, bypasses, swallowed errors, silent defaults, broad shims, alternate execution paths
+   - **Duplication** — repeated logic, copy-paste branches, redundant helpers
+   - **Dead code** — unused code, unreachable branches, stale flags, debug leftovers
+   - **Needless abstraction** — pass-through wrappers, speculative indirection, single-use helper layers
+   - **Boundary violations** — hidden coupling, leaky responsibilities, wrong-layer imports or side effects
+   - **UI/design slop** — review visual outputs as context-sensitive signals, not absolute bans; preserve intentional brand, design-system, accessibility, or product-context exceptions when the rationale is clear
+     - Korean body text that is too small: challenge 11-12px body copy; Korean body text generally needs 14px or larger unless a dense, accessible system explicitly supports smaller text
+     - Gratuitous depth: avoid putting box shadows on every logo, surface, card, icon, background, and step block when hierarchy or affordance does not need it
+     - Repetitive content scaffolding: trim repeated eyebrow + title + description + paragraph stacks, filler explanation text, and generic emoji badges that do not add meaning
+     - Default AI palettes: question blue/purple defaults such as #3B82F6 when there is no brand, semantic, or system rationale
+     - Over-perfect grids: avoid reflexive uniform 3-column or 4-column card grids when the product context would benefit from rhythm, asymmetry, carousel cuts, bento composition, or varied emphasis
+     - Extreme gradients: tone down "AI demo" gradients unless the brand or campaign intentionally calls for that intensity
+   - **Missing tests** — behavior not locked, weak regression coverage, gaps around edge cases
+
+5. **Execute passes one smell at a time**
+   - **Fallback-like code resolution gate** — remove masking fallback slop, repair root causes, or escalate ambiguous cases before continuing
+   - **Pass 1: Dead code deletion**
+   - **Pass 2: Duplicate removal**
+   - **Pass 3: Naming/error handling cleanup**
+   - **Pass 4: Test reinforcement**
+   - Re-run targeted verification after each pass
+   - Avoid bundling unrelated refactors into the same edit set
+
+6. **Run quality gates**
+   - Regression tests stay green
+   - Lint passes
+   - Typecheck passes
+   - Relevant unit/integration tests pass
+   - Static/security scan passes when available
+   - Diff stays minimal and scoped
+   - No new abstractions or dependencies unless explicitly required
+
+7. **Finish with an evidence-dense report**
+   - Changed files
+   - Simplifications made
+   - Fallback findings, classifications, and escalation status
+   - Tests/diagnostics/build checks run
+   - UI/design reviewer checklist findings when visual/UI files were in scope
+   - Remaining risks
+   - Residual follow-ups or consciously deferred cleanup
+
+## Output Format
+
+```text
+AI SLOP CLEANUP REPORT
+======================
+
+Scope: [files or feature area]
+Behavior Lock: [targeted regression tests added/run]
+Cleanup Plan: [bounded smells and order]
+Fallback Findings: [none, or finding -> masking fallback slop / grounded compatibility/fail-safe fallback -> escalation status]
+UI/Design Findings: [none/N/A, or signal -> action taken/deferred -> intentional exception rationale]
+
+Passes Completed:
+- Fallback-like code resolution gate - [root-cause repair, explicit failure behavior, preserved grounded fallback, or ralplan handoff]
+1. Pass 1: Dead code deletion - [concise fix]
+2. Pass 2: Duplicate removal - [concise fix]
+3. Pass 3: Naming/error handling cleanup - [concise fix]
+4. Pass 4: Test reinforcement - [concise fix]
+
+Quality Gates:
+- Regression tests: PASS/FAIL
+- Lint: PASS/FAIL
+- Typecheck: PASS/FAIL
+- Tests: PASS/FAIL
+- Static/security scan: PASS/FAIL or N/A
+
+Changed Files:
+- [path] - [simplification]
+
+Fallback Review:
+- Findings: [fallback-like findings detected]
+- Classification: [masking fallback slop | grounded fallback]
+- Escalation Status: [none | raised to leader/ralplan | no escalation]
+
+Remaining Risks:
+- [none or short deferred item]
+```
+
+## Scenario Examples
+
+**Good:** The user says `continue` after tests already lock behavior and the next smell pass is clear. Continue with the next bounded cleanup pass.
+
+**Good:** The user narrows the scope to a specific file after planning. Keep the regression-tests-first workflow, but apply the new scope locally.
+
+**Bad:** Start rewriting architecture before protecting behavior with tests.
+
+**Bad:** Collapse multiple smell categories into one large refactor with no intermediate verification.
+
+**Bad:** Keep a `fallback if it fails` branch that silently defaults after a swallowed error instead of fixing the root cause or making failure explicit.
+
+**Good:** A version-specific compatibility shim is narrow, documented, preserves error evidence, has primary and fallback regression tests, and is reported as a grounded compatibility/fail-safe fallback.

package/skills/analyze/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: analyze
+description: "Run read-only deep repository analysis and return a ranked synthesis with explicit confidence, concrete file references, and clear evidence-vs-inference boundaries. Use when a user says 'analyze', 'investigate', 'why does', 'what's causing', or needs grounded cross-file explanation before any changes are proposed."
+---
+
+# Analyze — Read-Only Deep Analysis
+
+Use this skill to answer the user’s question through **read-only repository analysis**. The goal is to explain what the codebase most likely says about the question, not to drift into implementation, debugging theater, or generic fix planning.
+
+## Use `$analyze` when
+
+- the user wants a grounded explanation, not code changes
+- the answer requires reading multiple files or tracing behavior across boundaries
+- there are several plausible explanations and they need to be ranked
+- confidence should reflect the strength of the available evidence
+- the user wants to understand architecture, behavior, causality, impact, or tradeoffs before changing anything
+
+Examples:
+- why a workflow behaves a certain way
+- how a feature is wired across modules
+- what likely explains a failure, regression, or mismatch
+- what would be impacted by changing a dependency or contract
+- which interpretation of the current codebase is best supported
+
+## Do not use `$analyze` when
+
+- the user explicitly wants code edits, a fix, or execution — use the appropriate implementation lane instead
+- the user wants a new product plan or acceptance criteria — use `$plan` / `$ralplan`
+- the request is a simple one-file fact lookup — read the file and answer directly
+- the request is purely about running the OMX tmux team runtime — use `$team` only when OMX runtime is active
+
+## Non-negotiable contract
+
+Analyze is **read-only by contract**.
+
+- Do not edit files.
+- Do not turn the answer into an implementation plan.
+- Do not recommend fixes as the primary output.
+- Do not silently switch into execution work.
+- Do not overclaim certainty.
+- Do not invent facts that are not supported by repository evidence.
+- Do not use judgmental, normative, or speculative language that outruns the evidence.
+
+If a next step is helpful, keep it to a **discriminating read-only probe** that would reduce uncertainty.
+
+## Question-aligned synthesis
+
+Answer the user’s actual question first.
+
+- Start from the asked question, not a generic debugger template.
+- Keep the synthesis scoped to what the user needs to know.
+- Scale the depth to the request: for simple or obvious questions, reduce swarm intensity and answer directly after enough reading.
+- For broader questions, expand the search surface but keep the final answer tightly synthesized.
+
+## Evidence rules
+
+Maintain an explicit **evidence-vs-inference distinction**. Every material claim must be labeled as one of:
+
+1. **Evidence** — directly supported by concrete repository artifacts
+2. **Inference** — a reasoned conclusion drawn from evidence
+3. **Unknown** — a question the current repository evidence does not resolve
+
+Never present an inference as if it were direct evidence.
+Never present a guess as if it were an inference.
+Call out uncertainty explicitly when the codebase does not settle the question.
+
+### Acceptable evidence
+
+Prefer stronger evidence over weaker evidence:
+
+1. direct code paths, contracts, tests, generated artifacts, configs, or docs with concrete file references
+2. multiple independent files pointing to the same conclusion
+3. localized behavioral inference from well-supported code structure
+4. weaker contextual clues that remain explicitly marked as tentative
+
+Unsupported speculation is not evidence.
+
+## Parallel exploration policy
+
+Parallel exploration is allowed when it improves quality, but it must stay runtime-safe.
+
+- Default to direct read-only analysis when the answer is simple.
+- When parallelism helps, prefer **native subagents by default** or equivalent in-session parallel exploration when available.
+- Keep parallel lanes bounded: each lane should answer a concrete sub-question or inspect a specific subsystem.
+- Use **`$team` only when OMX runtime is active** and durable tmux-based coordination is actually needed.
+- Do not imply that `$team` is available in plain Codex/App sessions.
+
+A good default split for complex analysis is:
+- one lane for primary code path / contracts
+- one lane for config / orchestration / generated surfaces
+- one lane for tests / docs / secondary corroboration
+
+## Execution policy
+
+- Default to outcome-first progress and completion reporting: state the question, evidence, inference boundaries, and stop condition before adding process detail.
+- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
+- If the user says `continue`, keep working from the current analysis state instead of restarting discovery.
+
+## Working method
+
+1. Restate the question in one sentence.
+2. Identify the smallest set of files most likely to answer it.
+3. Read for direct evidence first.
+4. If needed, open bounded parallel exploration lanes.
+5. Compare competing explanations.
+6. Rank the explanations by support.
+7. Return a synthesis that clearly separates evidence from inference.
+
+## Output contract
+
+Structure the answer so the user can see what is known, what is inferred, and how confident the synthesis is.
+
+### Question
+[Restate the user’s question briefly]
+
+### Ranked synthesis
+| Rank | Explanation | Confidence | Basis |
+|------|-------------|------------|-------|
+| 1 | ... | High / Medium / Low | strongest supporting evidence |
+| 2 | ... | High / Medium / Low | why it trails |
+| 3 | ... | High / Medium / Low | why it remains possible |
+
+### Evidence
+- `path/to/file:line-line` — what this artifact directly shows
+- `path/to/file:line-line` — corroborating evidence
+
+### Inference
+- What the evidence most strongly implies
+- Why weaker alternatives were down-ranked
+
+### Unknowns / limits
+- What the repository evidence does not establish
+- What would need to be checked next to reduce uncertainty
+
+## Quality bar
+
+A good analyze response is:
+- read-only and question-aligned
+- ranked rather than flat
+- explicit about confidence
+- concrete about file references
+- careful about evidence vs inference
+- free of unsupported speculation
+- free of normative drift or judgmental filler
+- explicit about the evidence-vs-inference distinction
+- concise for simple cases, broader only when the question truly needs it

package/skills/ask/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: ask
+description: Ask a local external advisor CLI (Claude or Gemini) and capture a reusable artifact
+---
+
+# Ask (Local Advisor CLI)
+
+Use a locally installed external advisor CLI for focused questions, reviews, brainstorming, or second opinions. This skill replaces the separate `ask-claude` and `ask-gemini` skills.
+
+## Usage
+
+```bash
+$ask claude <question or task>
+$ask gemini <question or task>
+omx ask claude "<question or task>"
+omx ask gemini "<question or task>"
+```
+
+## Backend selection
+
+- Use `claude` when the user asks for Claude, Anthropic, or the previous `$ask-claude` behavior.
+- Use `gemini` when the user asks for Gemini or the previous `$ask-gemini` behavior.
+- If no backend is specified, choose the installed backend that best matches the user request; if neither is clearly available, explain that a local CLI is required.
+
+## Local CLI commands
+
+Claude:
+
+```bash
+omx ask claude "{{ARGUMENTS}}"
+claude -p "{{ARGUMENTS}}"
+```
+
+Gemini:
+
+```bash
+omx ask gemini "{{ARGUMENTS}}"
+gemini -p "{{ARGUMENTS}}"
+```
+
+If needed, adapt to the user's installed CLI variant while keeping local execution as the default path. Do not silently switch to an MCP or remote provider when the local binary is missing.
+
+## Artifact requirement
+
+After local execution, save a markdown artifact to:
+
+```text
+.omx/artifacts/ask-<backend>-<slug>-<timestamp>.md
+```
+
+Minimum artifact sections:
+1. Original user task
+2. Backend and final prompt sent to the CLI
+3. Raw CLI output
+4. Concise summary
+5. Action items / next steps
+
+Task: {{ARGUMENTS}}

package/skills/ask-claude/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: ask-claude
+description: Deprecated compatibility shim for Claude advisor requests
+---
+
+# Ask Claude compatibility shim
+
+Hard-deprecated. Do not invoke or route this skill for new work.
+
+Use `$ask claude <question>` or `omx ask claude "<question>"` directly for Claude advisor workflows. This file exists only to preserve the public/catalog-visible `ask-claude` skill contract while the canonical `$ask` workflow owns provider selection.
+
+Task: {{ARGUMENTS}}

package/skills/ask-gemini/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: ask-gemini
+description: Deprecated compatibility shim for Gemini advisor requests
+---
+
+# Ask Gemini compatibility shim
+
+Hard-deprecated. Do not invoke or route this skill for new work.
+
+Use `$ask gemini <question>` or `omx ask gemini "<question>"` directly for Gemini advisor workflows. This file exists only to preserve the public/catalog-visible `ask-gemini` skill contract while the canonical `$ask` workflow owns provider selection.
+
+Task: {{ARGUMENTS}}

package/skills/autopilot/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: autopilot
+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 recommended/default contract is exactly:
+
+```text
+$deep-interview -> $ralplan -> $ultragoal (+ $team if needed) -> $code-review -> $ultraqa
+```
+
+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 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
+</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.
+   - Run or resume `$ralplan` to produce/update PRD and test-spec artifacts.
+   - PRD/test-spec files alone are not completion evidence. Ralplan may hand off only after durable consensus evidence records a subsequent `Architect` approval first and a subsequent `Critic` approval second.
+   - 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: an approved plan/test spec plus `ralplan_consensus_gate` evidence suitable for `$ultragoal`.
+
+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`.
+
+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`.
+
+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>
+
+<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` 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`, `$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>
+
+<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:
+
+```json
+{
+  "mode": "autopilot",
+  "active": true,
+  "current_phase": "deep-interview",
+  "iteration": 1,
+  "review_cycle": 0,
+  "max_iterations": 10,
+  "phase_cycle": ["deep-interview", "ralplan", "ultragoal", "code-review", "ultraqa"],
+  "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
+  },
+  "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.
+  - **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`, with tracker-backed native-subagent `ralplan_architect_review.agent_role:"architect"` and `ralplan_architect_review.verdict:"approve"` recorded before tracker-backed native-subagent `ralplan_critic_review.agent_role:"critic"` and `ralplan_critic_review.verdict:"approve"`; `codex_exec` or artifact-only approvals are trace evidence but not native lane proof. Set `current_phase:"ultragoal"` and persist the plan/test-spec paths under `handoff_artifacts.ralplan`.
+- **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 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 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`.
+- `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 default Autopilot pipeline contract is:
+
+```text
+deep-interview -> ralplan -> ultragoal -> code-review -> ultraqa
+```
+
+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 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>
+
+<Final_Checklist>
+- [ ] Phase `deep-interview` produced/updated clarified requirements or a concise spec
+- [ ] Phase `ralplan` produced/updated approved planning artifacts and durable sequential evidence from a subsequent `Architect` approval followed by a subsequent `Critic` approval
+- [ ] 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`)
+- [ ] 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
+</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.
+</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.
+</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.
+</Bad>
+</Examples>