oh-my-codex 0.18.13 → 0.18.14

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

@@ -37,7 +37,8 @@ Autopilot must not run a separate broad expansion/planning/execution/QA/validati
 
 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.
+   - 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. 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.
@@ -53,7 +54,7 @@ Autopilot must not run a separate broad expansion/planning/execution/QA/validati
    - 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`.
+   - 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.
@@ -84,7 +85,7 @@ Before Phase `deep-interview` or `ralplan` starts or resumes:
 - 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.
+- 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.
@@ -140,8 +141,9 @@ Required fields:
 - **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 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.
+- **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.
 </State_Management>
@@ -151,6 +153,7 @@ When the user says `continue`, `resume`, or `keep going` while Autopilot is acti
 - `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.
@@ -167,7 +170,7 @@ Autopilot may be represented by the configurable pipeline orchestrator (`src/pip
 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 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>
 
 <Escalation_And_Stop_Conditions>
@@ -181,6 +184,7 @@ Pipeline state should use `current_phase` values that match the same phase names
 - [ ] 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
+- [ ] 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

package/plugins/oh-my-codex/skills/autoresearch-goal/SKILL.md

@@ -31,6 +31,9 @@ Use this workflow when a research mission should be bound to Codex goal-mode foc
 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.

package/plugins/oh-my-codex/skills/performance-goal/SKILL.md

@@ -55,6 +55,7 @@ omx performance-goal complete --slug startup-latency --evidence "final evaluator
    - call `create_goal` only when no active goal exists and the objective is explicit;
    - work only against the evaluator contract;
    - after evaluator pass and completion audit, call `update_goal({status: "complete"})`, call `get_goal` again, and pass that snapshot to `omx performance-goal complete --codex-goal-json`;
+   - after `omx performance-goal complete` 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;
 3. Optimize in small reversible patches.
 4. Run the evaluator and related regression tests.
 5. Record each pass/fail/blocker with `checkpoint`.
@@ -63,3 +64,5 @@ omx performance-goal complete --slug startup-latency --evidence "final evaluator
 ## Completion Gate
 
 A performance goal is incomplete unless `.omx/goals/performance/<slug>/state.json` contains a `lastValidation.status` of `pass` and `omx performance-goal complete` receives a matching complete Codex `get_goal` snapshot via `--codex-goal-json`. Passing ordinary tests alone is not sufficient unless they are the declared evaluator contract.
+
+Lifecycle: `create_goal` starts the Codex thread goal, `update_goal({status: "complete"})` marks terminal success after the evaluator 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.

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

@@ -42,7 +42,7 @@ $plan --consensus --interactive <arguments>
 ```
 
 The consensus workflow:
-1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review:
+1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review. Current `[main]` vs `[planner]` behavior: standalone `$ralplan` may be authored by the active main planning lane unless the caller/runtime supplies a dedicated planner routing record; inside `$autopilot`, state field `planning_routing.owner:"planner"` means the initial Planner draft/decomposition must use dedicated `[planner]`. Set `.omx-config.json` `agentModels.planner` to opt into a specific planner model and force dedicated planner ownership for complex Autopilot planning even when `[main]` is not cheap/mini. The RALPLAN-DR summary includes:
    - Principles (3-5)
    - Decision Drivers (top 3)
    - Viable Options (>=2) with bounded pros/cons

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

@@ -94,8 +94,10 @@ The final ultragoal story is not complete until the active agent has run the fin
 1. Run targeted verification for the story.
 2. Run `ai-slop-cleaner` on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
 3. Rerun verification after the cleaner pass.
-4. Run `$code-review` through the independent review path. Clean means `codeReview.recommendation: "APPROVE"`, `codeReview.architectStatus: "CLEAR"`, and `codeReview.independentReview` contains distinct completed `code-reviewer` and `architect` subagent evidence. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing subagent evidence, unavailable delegation, and same-lane/self-review are non-clean.
-5. If review is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+4. Run the architecture-invariant audit: derive non-negotiable architecture/domain invariants from the brief/spec/interview/accepted steering/goal artifacts, list the source artifacts, and prove each required invariant with implementation, test, and independent review evidence.
+5. Run `$code-review` through the independent review path. Clean means `codeReview.recommendation: "APPROVE"`, `codeReview.architectStatus: "CLEAR"`, `codeReview.independentReview` contains distinct completed `code-reviewer` and `architect` subagent evidence, and `architectureInvariantGate.status: "passed"` proves every required invariant. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing subagent evidence, unavailable delegation, same-lane/self-review, and unproved architecture invariants are non-clean.
+6. If review or invariant proof is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+
 
    ```sh
    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>
@@ -103,7 +105,8 @@ The final ultragoal story is not complete until the active agent has run the fin
 
    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:
+7. If review and invariant proof are clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with a structured final gate:
+
 
    ```sh
    omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<tests/files/review evidence>" --codex-goal-json <fresh-complete-get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
@@ -123,6 +126,21 @@ The final ultragoal story is not complete until the active agent has run the fin
       "codeReviewer": { "agentRole": "code-reviewer", "evidence": "code-reviewer subagent APPROVE evidence" },
       "architect": { "agentRole": "architect", "evidence": "architect subagent CLEAR evidence" }
     }
+  },
+  "architectureInvariantGate": {
+    "status": "passed",
+    "sourceArtifacts": [".omx/ultragoal/brief.md", ".omx/ultragoal/goals.json"],
+    "evidence": "final invariant audit proved all required architecture/domain invariants",
+    "invariants": [
+      {
+        "invariant": "Preserve the existing parser boundary.",
+        "source": ".omx/ultragoal/brief.md#architecture-invariants",
+        "status": "proved",
+        "implementationEvidence": "changed files preserve the parser boundary",
+        "testEvidence": "parser-boundary regression passed",
+        "reviewEvidence": "architect review confirmed the boundary is intact"
+      }
+    ]
   }
 }
 ```
@@ -131,7 +149,7 @@ The final ultragoal story is not complete until the active agent has run the fin
 
 - 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.
+- After a completed aggregate ultragoal run, `/goal clear` is the explicit terminal cleanup step before starting another goal in the same Codex thread/session: `create_goal` starts, `update_goal({status: "complete"})` marks terminal success, and `/goal clear` removes the completed thread goal for the next same-thread goal. OMX prints this next step but does not invoke hidden clear routes.
 - 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

@@ -35,7 +35,7 @@ Sequential task execution wastes time when tasks are independent. Ultrawork keep
 - When useful, run a direct-tool lane and one or more background evidence lanes at the same time. Evidence lanes can cover docs, tests, regression mapping, or bounded repo analysis.
 - Fire independent agent calls simultaneously -- never serialize independent work.
 - Always pass the `model` parameter explicitly when delegating.
-- Read `docs/shared/agent-tiers.md` before first delegation for agent selection guidance.
+- Read `references/agent-tiers.md` before first delegation for agent selection guidance.
 - Auto-delegate `researcher` when official docs, version-aware framework guidance, best practices, or external dependency behavior materially affect task correctness; treat it as an evidence lane, not a replacement primary workflow.
 - Use `run_in_background: true` for operations over ~30 seconds (installs, builds, tests).
 - Run quick commands (git status, file reads, simple checks) in the foreground.
@@ -44,7 +44,7 @@ Sequential task execution wastes time when tasks are independent. Ultrawork keep
 </Execution_Policy>
 
 <Steps>
-1. **Read agent reference**: Load `docs/shared/agent-tiers.md` for tier selection.
+1. **Read agent reference**: Load `references/agent-tiers.md` for tier selection.
 2. **Context + certainty check**:
    - State the task intent in one sentence.
    - List the constraints and unknowns that could invalidate a quick fix.

package/plugins/oh-my-codex/skills/ultrawork/references/agent-tiers.md

@@ -0,0 +1,61 @@
+# Agent Tiers
+
+This file defines practical tier guidance for OMX agent routing.
+
+## Mental Model
+
+OMX now separates three concepts:
+
+- `role`: what the agent is responsible for (`executor`, `planner`, `architect`)
+- `tier`: how much reasoning/cost to spend (`LOW`, `STANDARD`, `THOROUGH`)
+- `posture`: how the role behaves (`frontier-orchestrator`, `deep-worker`, `fast-lane`)
+- `exactModel`: optional role pin that bypasses tier defaults when a role needs a
+  specific model contract.
+
+Use role to choose responsibility, tier to choose depth, and posture to choose operating style.
+
+## Tiers
+
+- `LOW`:
+  Fast lookups and narrow checks.
+  Use for simple exploration, style checks, and lightweight doc edits.
+  Typical roles: `explore`, `style-reviewer`, `writer`.
+
+- `STANDARD`:
+  Default tier for implementation, debugging, and normal verification.
+  Typical roles: `executor`, `debugger`, `test-engineer`, `quality-reviewer`.
+
+- `THOROUGH`:
+  Use for architectural, security-sensitive, or high-impact multi-file work.
+  Typical roles: `architect`, `critic`, `security-reviewer`, `executor`.
+  Note: `deep-executor` is deprecated; route implementation to `executor`.
+
+## Selection Rules
+
+1. Start at `STANDARD` for most code changes.
+2. Use `LOW` only when the task is bounded and non-invasive.
+3. Escalate to `THOROUGH` for:
+   - security/auth/trust-boundary changes
+   - architectural decisions with system-wide impact
+   - large refactors across many files
+4. For Ralph completion checks, use at least `STANDARD` architect verification.
+
+## Posture Guidance
+
+- `frontier-orchestrator`:
+  - Best for steerable frontier models and leader-style roles.
+  - Prioritizes intent classification, delegation, verification, and architectural judgment.
+  - Typical roles: `planner`, `analyst`, `architect`, `critic`, `code-reviewer`.
+  - Ralplan keeps `planner` and `architect` in this posture but pins them to
+    exact `gpt-5.4-mini` with high reasoning; the `critic` consensus gate stays
+    on the frontier lane.
+
+- `deep-worker`:
+  - Best for implementation-heavy roles that should carry work to completion.
+  - Prioritizes direct execution, minimal diffs, and strict verification.
+  - Typical roles: `executor`, `debugger`, `test-engineer`, `build-fixer`.
+
+- `fast-lane`:
+  - Best for cheap/fast models used for triage, search, and narrow synthesis.
+  - Prioritizes quick routing, concise search, and escalation over deep autonomous work.
+  - Typical roles: `explore`, `writer`, and lightweight research/search specialists.

package/skills/autopilot/SKILL.md

@@ -37,7 +37,8 @@ Autopilot must not run a separate broad expansion/planning/execution/QA/validati
 
 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.
+   - 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. 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.
@@ -53,7 +54,7 @@ Autopilot must not run a separate broad expansion/planning/execution/QA/validati
    - 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`.
+   - 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.
@@ -84,7 +85,7 @@ Before Phase `deep-interview` or `ralplan` starts or resumes:
 - 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.
+- 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.
@@ -140,8 +141,9 @@ Required fields:
 - **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 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.
+- **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.
 </State_Management>
@@ -151,6 +153,7 @@ When the user says `continue`, `resume`, or `keep going` while Autopilot is acti
 - `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.
@@ -167,7 +170,7 @@ Autopilot may be represented by the configurable pipeline orchestrator (`src/pip
 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 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>
 
 <Escalation_And_Stop_Conditions>
@@ -181,6 +184,7 @@ Pipeline state should use `current_phase` values that match the same phase names
 - [ ] 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
+- [ ] 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

package/skills/autoresearch-goal/SKILL.md

@@ -31,6 +31,9 @@ Use this workflow when a research mission should be bound to Codex goal-mode foc
 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.

package/skills/ecomode/SKILL.md

@@ -47,7 +47,7 @@ Ecomode is a modifier that combines with execution modes:
 
 **FIRST ACTION:** Before delegating any work, read the agent reference file:
 ```
-Read file: docs/shared/agent-tiers.md
+Read file: references/agent-tiers.md
 ```
 This provides the complete agent tier matrix, MCP tool assignments, and selection guidance.
 

package/skills/ecomode/references/agent-tiers.md

@@ -0,0 +1,61 @@
+# Agent Tiers
+
+This file defines practical tier guidance for OMX agent routing.
+
+## Mental Model
+
+OMX now separates three concepts:
+
+- `role`: what the agent is responsible for (`executor`, `planner`, `architect`)
+- `tier`: how much reasoning/cost to spend (`LOW`, `STANDARD`, `THOROUGH`)
+- `posture`: how the role behaves (`frontier-orchestrator`, `deep-worker`, `fast-lane`)
+- `exactModel`: optional role pin that bypasses tier defaults when a role needs a
+  specific model contract.
+
+Use role to choose responsibility, tier to choose depth, and posture to choose operating style.
+
+## Tiers
+
+- `LOW`:
+  Fast lookups and narrow checks.
+  Use for simple exploration, style checks, and lightweight doc edits.
+  Typical roles: `explore`, `style-reviewer`, `writer`.
+
+- `STANDARD`:
+  Default tier for implementation, debugging, and normal verification.
+  Typical roles: `executor`, `debugger`, `test-engineer`, `quality-reviewer`.
+
+- `THOROUGH`:
+  Use for architectural, security-sensitive, or high-impact multi-file work.
+  Typical roles: `architect`, `critic`, `security-reviewer`, `executor`.
+  Note: `deep-executor` is deprecated; route implementation to `executor`.
+
+## Selection Rules
+
+1. Start at `STANDARD` for most code changes.
+2. Use `LOW` only when the task is bounded and non-invasive.
+3. Escalate to `THOROUGH` for:
+   - security/auth/trust-boundary changes
+   - architectural decisions with system-wide impact
+   - large refactors across many files
+4. For Ralph completion checks, use at least `STANDARD` architect verification.
+
+## Posture Guidance
+
+- `frontier-orchestrator`:
+  - Best for steerable frontier models and leader-style roles.
+  - Prioritizes intent classification, delegation, verification, and architectural judgment.
+  - Typical roles: `planner`, `analyst`, `architect`, `critic`, `code-reviewer`.
+  - Ralplan keeps `planner` and `architect` in this posture but pins them to
+    exact `gpt-5.4-mini` with high reasoning; the `critic` consensus gate stays
+    on the frontier lane.
+
+- `deep-worker`:
+  - Best for implementation-heavy roles that should carry work to completion.
+  - Prioritizes direct execution, minimal diffs, and strict verification.
+  - Typical roles: `executor`, `debugger`, `test-engineer`, `build-fixer`.
+
+- `fast-lane`:
+  - Best for cheap/fast models used for triage, search, and narrow synthesis.
+  - Prioritizes quick routing, concise search, and escalation over deep autonomous work.
+  - Typical roles: `explore`, `writer`, and lightweight research/search specialists.

package/skills/performance-goal/SKILL.md

@@ -55,6 +55,7 @@ omx performance-goal complete --slug startup-latency --evidence "final evaluator
    - call `create_goal` only when no active goal exists and the objective is explicit;
    - work only against the evaluator contract;
    - after evaluator pass and completion audit, call `update_goal({status: "complete"})`, call `get_goal` again, and pass that snapshot to `omx performance-goal complete --codex-goal-json`;
+   - after `omx performance-goal complete` 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;
 3. Optimize in small reversible patches.
 4. Run the evaluator and related regression tests.
 5. Record each pass/fail/blocker with `checkpoint`.
@@ -63,3 +64,5 @@ omx performance-goal complete --slug startup-latency --evidence "final evaluator
 ## Completion Gate
 
 A performance goal is incomplete unless `.omx/goals/performance/<slug>/state.json` contains a `lastValidation.status` of `pass` and `omx performance-goal complete` receives a matching complete Codex `get_goal` snapshot via `--codex-goal-json`. Passing ordinary tests alone is not sufficient unless they are the declared evaluator contract.
+
+Lifecycle: `create_goal` starts the Codex thread goal, `update_goal({status: "complete"})` marks terminal success after the evaluator 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.

package/skills/ralplan/SKILL.md

@@ -42,7 +42,7 @@ $plan --consensus --interactive <arguments>
 ```
 
 The consensus workflow:
-1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review:
+1. **Planner** creates an adaptive plan (right-sized to task scope; do not default to exactly five steps) and a compact **RALPLAN-DR summary** before review. Current `[main]` vs `[planner]` behavior: standalone `$ralplan` may be authored by the active main planning lane unless the caller/runtime supplies a dedicated planner routing record; inside `$autopilot`, state field `planning_routing.owner:"planner"` means the initial Planner draft/decomposition must use dedicated `[planner]`. Set `.omx-config.json` `agentModels.planner` to opt into a specific planner model and force dedicated planner ownership for complex Autopilot planning even when `[main]` is not cheap/mini. The RALPLAN-DR summary includes:
    - Principles (3-5)
    - Decision Drivers (top 3)
    - Viable Options (>=2) with bounded pros/cons

package/skills/ultragoal/SKILL.md

@@ -94,8 +94,10 @@ The final ultragoal story is not complete until the active agent has run the fin
 1. Run targeted verification for the story.
 2. Run `ai-slop-cleaner` on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
 3. Rerun verification after the cleaner pass.
-4. Run `$code-review` through the independent review path. Clean means `codeReview.recommendation: "APPROVE"`, `codeReview.architectStatus: "CLEAR"`, and `codeReview.independentReview` contains distinct completed `code-reviewer` and `architect` subagent evidence. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing subagent evidence, unavailable delegation, and same-lane/self-review are non-clean.
-5. If review is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+4. Run the architecture-invariant audit: derive non-negotiable architecture/domain invariants from the brief/spec/interview/accepted steering/goal artifacts, list the source artifacts, and prove each required invariant with implementation, test, and independent review evidence.
+5. Run `$code-review` through the independent review path. Clean means `codeReview.recommendation: "APPROVE"`, `codeReview.architectStatus: "CLEAR"`, `codeReview.independentReview` contains distinct completed `code-reviewer` and `architect` subagent evidence, and `architectureInvariantGate.status: "passed"` proves every required invariant. `COMMENT`, `WATCH`, `REQUEST CHANGES`, `BLOCK`, missing subagent evidence, unavailable delegation, same-lane/self-review, and unproved architecture invariants are non-clean.
+6. If review or invariant proof is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+
 
    ```sh
    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>
@@ -103,7 +105,8 @@ The final ultragoal story is not complete until the active agent has run the fin
 
    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:
+7. If review and invariant proof are clean, call `update_goal({status: "complete"})`, call `get_goal`, and checkpoint with a structured final gate:
+
 
    ```sh
    omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<tests/files/review evidence>" --codex-goal-json <fresh-complete-get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
@@ -123,6 +126,21 @@ The final ultragoal story is not complete until the active agent has run the fin
       "codeReviewer": { "agentRole": "code-reviewer", "evidence": "code-reviewer subagent APPROVE evidence" },
       "architect": { "agentRole": "architect", "evidence": "architect subagent CLEAR evidence" }
     }
+  },
+  "architectureInvariantGate": {
+    "status": "passed",
+    "sourceArtifacts": [".omx/ultragoal/brief.md", ".omx/ultragoal/goals.json"],
+    "evidence": "final invariant audit proved all required architecture/domain invariants",
+    "invariants": [
+      {
+        "invariant": "Preserve the existing parser boundary.",
+        "source": ".omx/ultragoal/brief.md#architecture-invariants",
+        "status": "proved",
+        "implementationEvidence": "changed files preserve the parser boundary",
+        "testEvidence": "parser-boundary regression passed",
+        "reviewEvidence": "architect review confirmed the boundary is intact"
+      }
+    ]
   }
 }
 ```
@@ -131,7 +149,7 @@ The final ultragoal story is not complete until the active agent has run the fin
 
 - 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.
+- After a completed aggregate ultragoal run, `/goal clear` is the explicit terminal cleanup step before starting another goal in the same Codex thread/session: `create_goal` starts, `update_goal({status: "complete"})` marks terminal success, and `/goal clear` removes the completed thread goal for the next same-thread goal. OMX prints this next step but does not invoke hidden clear routes.
 - 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/skills/ultrawork/SKILL.md

@@ -35,7 +35,7 @@ Sequential task execution wastes time when tasks are independent. Ultrawork keep
 - When useful, run a direct-tool lane and one or more background evidence lanes at the same time. Evidence lanes can cover docs, tests, regression mapping, or bounded repo analysis.
 - Fire independent agent calls simultaneously -- never serialize independent work.
 - Always pass the `model` parameter explicitly when delegating.
-- Read `docs/shared/agent-tiers.md` before first delegation for agent selection guidance.
+- Read `references/agent-tiers.md` before first delegation for agent selection guidance.
 - Auto-delegate `researcher` when official docs, version-aware framework guidance, best practices, or external dependency behavior materially affect task correctness; treat it as an evidence lane, not a replacement primary workflow.
 - Use `run_in_background: true` for operations over ~30 seconds (installs, builds, tests).
 - Run quick commands (git status, file reads, simple checks) in the foreground.
@@ -44,7 +44,7 @@ Sequential task execution wastes time when tasks are independent. Ultrawork keep
 </Execution_Policy>
 
 <Steps>
-1. **Read agent reference**: Load `docs/shared/agent-tiers.md` for tier selection.
+1. **Read agent reference**: Load `references/agent-tiers.md` for tier selection.
 2. **Context + certainty check**:
    - State the task intent in one sentence.
    - List the constraints and unknowns that could invalidate a quick fix.

package/skills/ultrawork/references/agent-tiers.md

@@ -0,0 +1,61 @@
+# Agent Tiers
+
+This file defines practical tier guidance for OMX agent routing.
+
+## Mental Model
+
+OMX now separates three concepts:
+
+- `role`: what the agent is responsible for (`executor`, `planner`, `architect`)
+- `tier`: how much reasoning/cost to spend (`LOW`, `STANDARD`, `THOROUGH`)
+- `posture`: how the role behaves (`frontier-orchestrator`, `deep-worker`, `fast-lane`)
+- `exactModel`: optional role pin that bypasses tier defaults when a role needs a
+  specific model contract.
+
+Use role to choose responsibility, tier to choose depth, and posture to choose operating style.
+
+## Tiers
+
+- `LOW`:
+  Fast lookups and narrow checks.
+  Use for simple exploration, style checks, and lightweight doc edits.
+  Typical roles: `explore`, `style-reviewer`, `writer`.
+
+- `STANDARD`:
+  Default tier for implementation, debugging, and normal verification.
+  Typical roles: `executor`, `debugger`, `test-engineer`, `quality-reviewer`.
+
+- `THOROUGH`:
+  Use for architectural, security-sensitive, or high-impact multi-file work.
+  Typical roles: `architect`, `critic`, `security-reviewer`, `executor`.
+  Note: `deep-executor` is deprecated; route implementation to `executor`.
+
+## Selection Rules
+
+1. Start at `STANDARD` for most code changes.
+2. Use `LOW` only when the task is bounded and non-invasive.
+3. Escalate to `THOROUGH` for:
+   - security/auth/trust-boundary changes
+   - architectural decisions with system-wide impact
+   - large refactors across many files
+4. For Ralph completion checks, use at least `STANDARD` architect verification.
+
+## Posture Guidance
+
+- `frontier-orchestrator`:
+  - Best for steerable frontier models and leader-style roles.
+  - Prioritizes intent classification, delegation, verification, and architectural judgment.
+  - Typical roles: `planner`, `analyst`, `architect`, `critic`, `code-reviewer`.
+  - Ralplan keeps `planner` and `architect` in this posture but pins them to
+    exact `gpt-5.4-mini` with high reasoning; the `critic` consensus gate stays
+    on the frontier lane.
+
+- `deep-worker`:
+  - Best for implementation-heavy roles that should carry work to completion.
+  - Prioritizes direct execution, minimal diffs, and strict verification.
+  - Typical roles: `executor`, `debugger`, `test-engineer`, `build-fixer`.
+
+- `fast-lane`:
+  - Best for cheap/fast models used for triage, search, and narrow synthesis.
+  - Prioritizes quick routing, concise search, and escalation over deep autonomous work.
+  - Typical roles: `explore`, `writer`, and lightweight research/search specialists.