oh-my-codex 0.16.3 → 0.17.0

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

@@ -0,0 +1,180 @@
+---
+name: design
+description: Canonical repo-local DESIGN.md workflow for product, UI/UX, and frontend decision source of truth
+---
+
+# Design Skill
+
+Use `$design` when product, UI/UX, frontend, or design-system decisions need a durable source of truth in the repository. This skill discovers existing design context, interviews for missing product/design information, and creates or refreshes repo-local `DESIGN.md` so future UI/UX/frontend work is grounded instead of improvised.
+
+## Purpose
+
+Make repo-local `DESIGN.md` source of truth and canonical design contract for the current repository:
+
+`existing repo evidence -> missing-context interview -> create/refresh DESIGN.md -> use DESIGN.md for UI/UX/frontend decisions`.
+
+The output is not a pixel-matching loop and not a one-off visual critique. It is the maintained design brief/checklist that implementation, review, and future visual work should cite.
+
+## Use when
+
+- The user asks for design direction, UX guidance, frontend planning, or design-system alignment.
+- A repo needs a design brief before UI/frontend implementation begins.
+- Existing UI/components/assets/screenshots need to be summarized into a reusable design source of truth.
+- UI/UX/frontend decisions are ambiguous and should be resolved through product context, constraints, and documented principles.
+- A feature needs `DESIGN.md` created or refreshed before `$ralph`, a designer lane, or implementation work proceeds.
+
+## Do not use when
+
+- The user provides or requests a visual reference/image/live URL and wants measured implementation until screenshots match. Use `$visual-ralph` for that visual-reference implementation loop.
+- The task is pure backend/API/infrastructure work with no user-facing design consequence.
+- The user only asks to compare screenshots or score visual fidelity. Use `$visual-ralph` and its built-in visual verdict flow.
+
+## Relationship to `$visual-ralph`
+
+`$design` owns the durable repo design source of truth: product goals, users, IA, visual language, components, accessibility, constraints, and open questions in `DESIGN.md`.
+
+`$visual-ralph` owns implementation against an approved generated/static/live-URL visual reference, with screenshot capture, Visual Ralph verdict scoring, and pixel-diff evidence. `$visual-ralph` may read `DESIGN.md`, and it may leave design-system artifacts behind, but it does not replace the `DESIGN.md` discovery/interview/refresh workflow.
+
+If both are needed, run `$design` first to establish the design contract, then run `$visual-ralph` only after the visual reference/baseline is approved.
+
+## Workflow
+
+### 1. Discover local design evidence
+
+Inspect the repository before writing guidance. Look for:
+
+- `DESIGN.md`, `docs/design*`, `docs/ux*`, `docs/frontend*`, `README.md`, product specs, PRDs, and issue notes.
+- Existing UI source: routes, pages, layouts, components, stories, examples, demos, theme files, CSS variables, Tailwind/theme config, tokens, icons, and assets.
+- Screenshots, mockups, brand files, logos, Figma/export notes, Storybook snapshots, Playwright screenshots, visual-regression baselines, or `.omx/artifacts/visual-ralph/*` references.
+- Accessibility, responsive, i18n, content, and platform constraints already encoded in code or docs.
+
+Record evidence with file paths. Distinguish observed facts from design inferences.
+
+### 2. Interview only for missing context
+
+Ask concise questions only when repo evidence cannot answer design-critical context. Prefer one focused round that closes the biggest gaps, such as:
+
+- target users/personas and jobs to be done,
+- product/business goals and non-goals,
+- brand personality or forbidden aesthetics,
+- primary flows and information architecture,
+- accessibility level, device/browser support, and implementation constraints,
+- existing design assets or references the repo does not contain.
+
+If the user wants autonomous progress or cannot answer, create `DESIGN.md` with explicit assumptions and open questions instead of blocking.
+
+### 3. Create or refresh `DESIGN.md`
+
+Use the structure below. Preserve useful existing content, remove contradictions, and mark unknowns as open questions. Keep it actionable for implementers and reviewers.
+
+#### Required `DESIGN.md` structure/checklist
+
+```markdown
+# Design
+
+## Source of truth
+- Status: Draft | Active | Needs refresh
+- Last refreshed: YYYY-MM-DD
+- Primary product surfaces:
+- Evidence reviewed:
+
+## Brand
+- Personality:
+- Trust signals:
+- Avoid:
+
+## Product goals
+- Goals:
+- Non-goals:
+- Success signals:
+
+## Personas and jobs
+- Primary personas:
+- User jobs:
+- Key contexts of use:
+
+## Information architecture
+- Primary navigation:
+- Core routes/screens:
+- Content hierarchy:
+
+## Design principles
+- Principle 1:
+- Principle 2:
+- Tradeoffs:
+
+## Visual language
+- Color:
+- Typography:
+- Spacing/layout rhythm:
+- Shape/radius/elevation:
+- Motion:
+- Imagery/iconography:
+
+## Components
+- Existing components to reuse:
+- New/changed components:
+- Variants and states:
+- Token/component ownership:
+
+## Accessibility
+- Target standard:
+- Keyboard/focus behavior:
+- Contrast/readability:
+- Screen-reader semantics:
+- Reduced motion and sensory considerations:
+
+## Responsive behavior
+- Supported breakpoints/devices:
+- Layout adaptations:
+- Touch/hover differences:
+
+## Interaction states
+- Loading:
+- Empty:
+- Error:
+- Success:
+- Disabled:
+- Offline/slow network, if applicable:
+
+## Content voice
+- Tone:
+- Terminology:
+- Microcopy rules:
+
+## Implementation constraints
+- Framework/styling system:
+- Design-token constraints:
+- Performance constraints:
+- Compatibility constraints:
+- Test/screenshot expectations:
+
+## Open questions
+- [ ] Question / owner / impact
+```
+
+### 4. Use `DESIGN.md` as the decision contract
+
+For UI/UX/frontend work after the refresh:
+
+- Cite the relevant `DESIGN.md` sections before making design choices.
+- Prefer existing components, tokens, and documented constraints.
+- If implementation reveals a design contradiction, update `DESIGN.md` or add an open question before proceeding.
+- Do not introduce a new design-system layer when existing repo-native patterns can be extended.
+
+### 5. Handoff to implementation or Visual Ralph when appropriate
+
+- For normal frontend implementation, hand off with the relevant `DESIGN.md` sections, repo evidence, and acceptance criteria.
+- For visual-reference/image/live-URL matching, hand off to `$visual-ralph` with the approved reference/baseline and note that `DESIGN.md` is supporting context, not the visual verdict target.
+
+## Completion checklist
+
+Do not declare the design workflow complete until:
+
+- Existing design docs/assets/components/screenshots have been inspected or explicitly noted as absent.
+- Missing product/design context has been answered, assumed, or listed in `DESIGN.md` open questions.
+- `DESIGN.md` exists at the repo root and contains all required checklist sections.
+- UI/UX/frontend recommendations cite `DESIGN.md` rather than relying on unstated preferences.
+- Any `$visual-ralph` handoff is clearly separated as visual implementation matching, not DESIGN.md governance.
+
+Task: {{ARGUMENTS}}

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

@@ -51,7 +51,7 @@ echo "Latest npm: $LATEST"
 - If no cache entry exists: INFO - plugin marketplace artifact not cached; this may be normal when OMX was installed only through npm/setup
 - Compare each printed `PLUGIN_VERSION` with `LATEST`; if it differs and is not `local`: WARN - outdated plugin cache
 - If one marketplace has multiple version directories: WARN - stale cache for that marketplace/plugin pair
-- Remember: plugin install/discovery is not a replacement for `npm install -g oh-my-codex` plus `omx setup`; the packaged plugin now carries plugin-scoped companion metadata for MCP servers and apps, while native/runtime hooks and the rest of OMX runtime wiring stay setup-owned
+- Remember: plugin install/discovery is not a replacement for `npm install -g oh-my-codex` plus `omx setup`; the packaged plugin carries plugin-scoped companion metadata for optional MCP compatibility servers and apps, with first-party MCP disabled by default, while native/runtime hooks and the rest of OMX runtime wiring stay setup-owned
 
 ### Step 2: Check Hook Configuration (config.toml + legacy settings.json)
 
@@ -123,7 +123,7 @@ ls -la ~/.agents/skills/ 2>/dev/null
 ```
 
 **Diagnosis**:
-- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy generated agents or hand-installed role files. The Codex plugin can package reusable workflows plus plugin-scoped companion metadata for MCP/apps; legacy setup installs native agents, while plugin setup archives stale legacy native-agent files and keeps config/hooks current.
+- If `~/.codex/agents/` exists with oh-my-codex-related files: WARN - legacy generated agents or hand-installed role files. The Codex plugin can package reusable workflows plus plugin-scoped companion metadata for optional MCP/apps; legacy setup installs native agents, while plugin setup archives stale legacy native-agent files and keeps config/hooks current.
 - If `~/.codex/commands/` exists with oh-my-codex-related files: WARN - legacy command files from older installs. Current OMX uses skills/workflows plus setup-managed native surfaces.
 - If `${CODEX_HOME:-~/.codex}/skills/` exists with OMX skills: OK - canonical current user skill root
 - If `~/.agents/skills/` exists: WARN - historical legacy skill root that can overlap with `${CODEX_HOME:-~/.codex}/skills/` and cause duplicate Enable/Disable Skills entries

package/plugins/oh-my-codex/skills/omx-setup/SKILL.md

@@ -60,7 +60,7 @@ Supported setup flags (current implementation):
   - `project`: local directories (`./.codex`, `./.codex/skills`, `./.omx/agents`)
 - User-scope skill delivery targets:
   - `legacy`: keep installing/updating OMX skills in the resolved user skill root
-  - `plugin`: rely on Codex plugin discovery for bundled skills and archive/remove legacy OMX-managed prompts/skills/native agents; setup still installs native Codex hooks and setup-owned runtime feature flags (`codex_hooks = true`, `goals = true`) because plugins do not carry hooks or enable Codex goal mode by themselves.
+  - `plugin`: rely on Codex plugin discovery for bundled skills and archive/remove legacy OMX-managed prompts/skills/native agents; setup still installs native Codex hooks and setup-owned runtime feature flags (`hooks = true` on current Codex, legacy `codex_hooks = true` when that is the only reported hook feature, plus `goals = true`) because plugins do not carry hooks or enable Codex goal mode by themselves.
 - Migration hint: in `user` scope, if historical `~/.agents/skills` still exists alongside `${CODEX_HOME:-~/.codex}/skills`, current setup prints a cleanup hint. **Why the paths differ**: `${CODEX_HOME:-~/.codex}/skills/` is the path current Codex CLI natively loads as its skill root; `~/.agents/skills/` was the skill root in an older Codex CLI release before `~/.codex` became the standard home directory. OMX writes only to the canonical `${CODEX_HOME:-~/.codex}/skills/` path. When both directories exist simultaneously, Codex discovers skills from both trees and may show duplicate entries in Enable/Disable Skills. Archive or remove `~/.agents/skills/` to resolve this.
 - If persisted scope is `project`, `omx` launch automatically uses `CODEX_HOME=./.codex` unless user explicitly overrides `CODEX_HOME`.
 - Plugin mode prompts separately for optional AGENTS.md defaults and optional `developer_instructions` defaults. If `developer_instructions` already exists, setup asks before overwriting it; non-interactive runs preserve it.
@@ -74,7 +74,7 @@ Use this map when reconciling setup behavior or debugging a confusing install:
 | Surface | Owner | Notes |
 | --- | --- | --- |
 | `./.omx/setup-scope.json` | `omx setup` | Persists setup scope and user-scope skill delivery mode. TTY reruns summarize it and offer keep/review/reset. |
-| `~/.codex/config.toml` / `./.codex/config.toml` | `omx setup` generated blocks + user edits | Setup refreshes OMX-managed blocks while preserving supported manual content; setup-owned runtime feature flags include `multi_agent`, `child_agents_md`, `codex_hooks`, and `goals`. |
+| `~/.codex/config.toml` / `./.codex/config.toml` | `omx setup` generated blocks + user edits | Setup refreshes OMX-managed blocks while preserving supported manual content; setup-owned runtime feature flags include `multi_agent`, `child_agents_md`, the Codex hook feature flag (`hooks` or legacy `codex_hooks`), and `goals`. |
 | `~/.codex/hooks.json` / `./.codex/hooks.json` | `omx setup` shared ownership | Setup owns OMX native hook wrappers and preserves user-owned hooks. |
 | prompts, skills, native agents | `omx setup` or Codex plugin delivery | Legacy mode installs local files; plugin mode relies on plugin discovery for bundled skills and archives/removes legacy OMX-managed prompt/native-agent copies. |
 | `AGENTS.md` | `omx setup` with overwrite safety | Generated defaults or managed refreshes are guarded by force/session checks. |
@@ -114,7 +114,7 @@ From `omx doctor`, expect:
 - Skills installed (scope-dependent: user or project)
 - AGENTS.md found in project root
 - `.omx/state` exists
-- OMX MCP servers configured in scope target `config.toml` (`~/.codex/config.toml` or `./.codex/config.toml`)
+- CLI-first config present in the scope target `config.toml`; first-party OMX MCP servers and shared MCP registry sync are omitted by default unless setup was run with `--mcp compat`
 
 ## Troubleshooting
 

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

@@ -52,9 +52,9 @@ return a `StageResult` with status, artifacts, and duration.
 Pipeline state persists via the ModeState system at `.omx/state/pipeline-state.json`.
 The HUD renders pipeline phase automatically. Resume is supported from the last incomplete stage.
 
-- **On start**: `state_write({mode: "pipeline", active: true, current_phase: "stage:ralplan"})`
-- **On stage transitions**: `state_write({mode: "pipeline", current_phase: "stage:<name>"})`
-- **On completion**: `state_write({mode: "pipeline", active: false, current_phase: "complete"})`
+- **On start**: `omx state write --input '{"mode":"pipeline","active":true,"current_phase":"stage:ralplan"}' --json`
+- **On stage transitions**: `omx state write --input '{"mode":"pipeline","current_phase":"stage:<name>"}' --json`
+- **On completion**: `omx state write --input '{"mode":"pipeline","active":false,"current_phase":"complete"}' --json`
 
 ## API
 

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

@@ -137,15 +137,13 @@ Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 </Steps>
 
 <Tool_Usage>
-- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
-- Use the surface-appropriate structured question path for preference questions (scope, priority, timeline, risk tolerance): attached-tmux OMX runtime uses `omx question`; outside tmux uses native structured input when available. Use plain text only as a last fallback for unsupported surfaces or highly specific free-form values.
-- `omx question` success JSON uses `answers[]` as the primary contract. For single-question planning prompts, read `answers[0].answer`; treat top-level `answer` as legacy compatibility fallback only.
-- Batch `questions[]` may be used for non-interview grouped preference or approval prompts when one submitted form is clearer than multiple interruptions; interview mode still asks one question per round.
+- Use `AskUserQuestion` for preference questions (scope, priority, timeline, risk tolerance) -- provides clickable UI
+- Use plain text for questions needing specific values (port numbers, names, follow-up clarifications)
 - Use the `explore` agent (LOW tier, bounded quick pass) to gather codebase facts before asking the user
 - Use `ask_codex` with `agent_role: "planner"` for planning validation on large-scope plans
 - Use `ask_codex` with `agent_role: "analyst"` for requirements analysis
 - Use `ask_codex` with `agent_role: "critic"` for plan review in consensus and review modes
-- If ToolSearch finds no MCP tools or Codex is unavailable, fall back to equivalent OMX prompt agents -- never block on external tools
+- If optional MCP compatibility tools or Codex consultation are unavailable, fall back to equivalent OMX prompt/native agents -- never block on external tools
 - **CRITICAL — Consensus mode agent calls MUST be sequential, never parallel.** Always await the Architect result before issuing the Critic call.
 - In consensus mode, default to RALPLAN-DR short mode; enable deliberate mode on `--deliberate` or explicit high-risk signals (auth/security, migrations, destructive changes, production incidents, compliance/PII, public API breakage)
 - In consensus mode with `--interactive`: use `AskUserQuestion` / the structured question UI for the user feedback step (step 2) and the final approval step (step 7) -- never ask for approval in plain text when a structured surface is available. Without `--interactive`, auto-proceed through planning steps without pausing. Output the final plan without execution.
@@ -153,7 +151,6 @@ Plans are saved to `.omx/plans/`. Drafts go to `.omx/drafts/`.
 - In consensus mode, execution follow-up handoff **MUST** include an explicit available-agent-types roster plus concrete staffing / role-allocation guidance grounded in that roster, suggested reasoning levels by lane, product-facing goal-mode follow-up suggestions (`$ultragoal` by default, `$autoresearch-goal` for research projects, `$performance-goal` for optimization/performance projects), explicit `omx team` / `$team` launch hints, and a team verification path
 </Tool_Usage>
 
-
 ## Scenario Examples
 
 **Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.

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

@@ -91,14 +91,13 @@ Complex tasks often fail silently: partial implementations get declared "done",
 </Steps>
 
 <Tool_Usage>
-- Before first MCP tool use, call `ToolSearch("mcp")` to discover deferred MCP tools
 - Use `ask_codex` with `agent_role: "architect"` for verification cross-checks when changes are security-sensitive, architectural, or involve complex multi-system integration
 - Skip Codex consultation for simple feature additions, well-tested changes, or time-critical verification
-- If ToolSearch finds no MCP tools or Codex is unavailable, proceed with architect agent verification alone -- never block on external tools
-- Use `state_write` / `state_read` for ralph mode state persistence between iterations
+- If MCP compatibility tools are unavailable, proceed with CLI/agent verification alone -- never block on external tools
+- Use `omx state write/read --input '<json>' --json` for ralph mode state persistence between iterations
 - Use Codex goal tools when present: `get_goal` to discover or re-check the active objective, `create_goal` only when the user/system explicitly requested a new goal and no active goal exists, and `update_goal` only after the audited objective is fully achieved.
 - Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context
-- If an `omx_state` MCP tool call reports that its stdio transport is unavailable/closed, do **not** retry the same MCP call. Retry once through the supported CLI parity surface with the same payload, preserving `workingDirectory` and `session_id`: `omx state write --input '<json>' --json`, `omx state read --input '<json>' --json`, or `omx state clear --input '<json>' --json`. If the CLI path also fails, continue with `.omx/context` / `.omx/plans` file-backed artifacts and report the state persistence blocker.
+- Prefer CLI state commands. If an explicit MCP compatibility `omx_state` call reports that its stdio transport is unavailable/closed, do **not** retry the same MCP call. Retry once through the supported CLI parity surface with the same payload, preserving `workingDirectory` and `session_id`: `omx state write --input '<json>' --json`, `omx state read --input '<json>' --json`, or `omx state clear --input '<json>' --json`. If the CLI path also fails, continue with `.omx/context` / `.omx/plans` file-backed artifacts and report the state persistence blocker.
 </Tool_Usage>
 
 ## Goal Mode Integration
@@ -118,18 +117,18 @@ Codex goal mode is the thread-level completion contract for long-running Ralph w
 
 ## State Management
 
-Use the `omx_state` MCP server tools (`state_write`, `state_read`, `state_clear`) for Ralph lifecycle state.
+Use the CLI-first state surface for Ralph lifecycle state (`omx state write/read/clear --input '<json>' --json`). Explicit MCP compatibility tools (`state_write`, `state_read`, `state_clear`) remain acceptable only when already enabled.
 
 - **On start**:
-  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
+  `omx state write --input '{"mode":"ralph","active":true,"iteration":1,"max_iterations":10,"current_phase":"executing","started_at":"<now>","state":{"context_snapshot_path":"<snapshot-path>"}}' --json`
 - **On each iteration**:
-  `state_write({mode: "ralph", iteration: <current>, current_phase: "executing"})`
+  `omx state write --input '{"mode":"ralph","iteration":<current>,"current_phase":"executing"}' --json`
 - **On verification/fix transition**:
-  `state_write({mode: "ralph", current_phase: "verifying"})` or `state_write({mode: "ralph", current_phase: "fixing"})`
+  `omx state write --input '{"mode":"ralph","current_phase":"verifying"}' --json` or `omx state write --input '{"mode":"ralph","current_phase":"fixing"}' --json`
 - **On completion**:
-  `state_write({mode: "ralph", active: false, current_phase: "complete", completed_at: "<now>"})`
+  `omx state write --input '{"mode":"ralph","active":false,"current_phase":"complete","completed_at":"<now>"}' --json`
 - **On cancellation/cleanup**:
-  run `$cancel` (which should call `state_clear(mode="ralph")`)
+  run `$cancel` (which should call `omx state clear --input '{"mode":"ralph"}' --json`)
 
 
 ## Scenario Examples

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

@@ -313,7 +313,8 @@ Project-only skills (2):
   - backend-scaffold
 
 Common skills (3):
-  - frontend-ui-ux
+  - design
+  - frontend-ui-ux (deprecated; use design or visual-ralph)
   - git-master
   - planner
 

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

@@ -34,15 +34,48 @@ Loop until `omx ultragoal status` reports all goals complete:
 4. If no active Codex goal exists, call `create_goal` with the printed payload. In aggregate mode, if the same aggregate Codex objective is already active, continue the current OMX story without creating a new Codex goal.
 5. Complete the current OMX story only.
 6. Run a completion audit against the story objective and real artifacts/tests.
-7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, call `update_goal({status: "complete"})`, then call `get_goal` again for a fresh `complete` snapshot.
-8. Checkpoint the durable ledger with that snapshot:
-   `omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path>`
+7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal` snapshot whose aggregate objective is still `active`. On the final story only, first run the mandatory final cleanup/review gate below; call `update_goal({status: "complete"})` only after that gate is clean, then call `get_goal` again for a fresh `complete` snapshot.
+8. Checkpoint the durable ledger with that snapshot. Intermediate aggregate checkpoints use only `--codex-goal-json`; final clean checkpoints also require `--quality-gate-json`:
+   `omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --codex-goal-json <get_goal-json-or-path> [--quality-gate-json <quality-gate-json-or-path>]`
 9. If blocked or failed, checkpoint failure:
    `omx ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
 10. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
    `omx ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json <get_goal-json-or-path>`
 11. Resume failed goals with `omx ultragoal complete-goals --retry-failed`.
 
+
+## Mandatory final cleanup and review gate
+
+The final ultragoal story is not complete until the active agent has run the final quality gate:
+
+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`. Clean means `codeReview.recommendation: "APPROVE"` and `codeReview.architectStatus: "CLEAR"`; `COMMENT`, `WATCH`, `REQUEST CHANGES`, and `BLOCK` are non-clean.
+5. If review 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>
+   ```
+
+   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the Codex goal active, and lets `omx ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need a fresh/available Codex goal context because the old per-story Codex goal remains active/incomplete.
+
+6. If review is 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>
+   ```
+
+`--quality-gate-json` must include:
+
+```json
+{
+  "aiSlopCleaner": { "status": "passed", "evidence": "cleaner report" },
+  "verification": { "status": "passed", "commands": ["npm test"], "evidence": "post-cleaner verification" },
+  "codeReview": { "recommendation": "APPROVE", "architectStatus": "CLEAR", "evidence": "final review synthesis" }
+}
+```
+
 ## Constraints
 
 - The shell command cannot directly invoke Codex interactive `/goal`; it emits a model-facing handoff for the active Codex agent.