# How the Visual Iteration Gate Uses $visual-verdict Scoring Thresholds in oh-my-codex

> Learn how the visual iteration gate in oh-my-codex uses $visual-verdict scoring thresholds to enforce quality checkpoints and block edits until visual fidelity is met.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: internals
- Published: 2026-04-03

---

**The visual iteration gate enforces a mandatory 90-point quality checkpoint by running `$visual-verdict` before every code edit, blocking progress until visual fidelity thresholds are met.**

The oh-my-codex repository implements a deterministic quality control system for visual-centric development tasks. At its core lies the **visual iteration gate**, a protocol that couples automated visual regression testing with strict scoring thresholds to prevent substandard UI changes from advancing through the development pipeline.

## What Is the Visual Iteration Gate?

The visual iteration gate is a built-in control point defined in the execution protocol at [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md). According to the source, the gate mandates that *"For visual tasks, run `$visual-verdict` every iteration before the next edit"* and requires persisting the verdict JSON in `.omx/state/{scope}/ralph-progress.json`【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/AGENTS.md#L77-L79】.

This gate acts as a hard blocker in the development loop. Unlike optional linting or soft warnings, the gate halts all forward progress—including commits, tests, or subsequent edits—until the visual output meets the defined quality standard.

## The $visual-verdict Scoring System

The `$visual-verdict` skill operates on a numeric scoring scale from 0 to 100, returning a JSON object with a `score` field representing visual fidelity against reference images. According to [`skills/visual-verdict/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/visual-verdict/SKILL.md), the skill declares a **pass threshold of 90+**, meaning any output scoring below 90 automatically triggers a revision requirement【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/skills/visual-verdict/SKILL.md#L44-L46】.

When invoked, the skill compares generated screenshots against reference images and produces structured feedback including:

- `score`: Integer 0-100 representing overall match quality
- `verdict`: String value ("pass" or "revise") derived from threshold evaluation  
- `differences`: Array of specific visual discrepancies detected
- `suggestions`: Actionable remediation steps to improve the score

## How the Gate Enforces Quality

The decision flow creates a mandatory feedback loop with no bypass mechanism. When a developer or automation script reaches the visual iteration gate, the system executes the following sequence:

1. **Invocation**: Run `$visual-verdict` with the current screenshot and reference images
2. **Evaluation**: Examine the `score` field in the returned JSON
3. **Branching logic**:
   - If `score >= 90`: The verdict passes, clearing the gate for the next stage (commit, test, or subsequent edits)
   - If `score < 90`: The gate **forces a revision**, requiring UI adjustments before any further code edits are permitted

The Ralph skill documentation explicitly reinforces this requirement, stating: *"Run `$visual-verdict` **before every next edit**"*【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/skills/ralph/SKILL.md#L66-L70】. This ensures that any Ralph-driven visual task inherits the iteration gate behavior automatically.

## Persistence and Audit Trail

Every verdict generated during the iteration loop must be persisted to `.omx/state/{scope}/ralph-progress.json`. This ledger serves as both an audit trail and a feedback mechanism for the Ralph loop, storing the complete JSON output including the numeric `score`, qualitative `reasoning`, and specific `suggestions`【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/AGENTS.md#L77-L80】.

The persistence layer enables deterministic recovery and historical analysis. By writing state to the scoped directory structure, oh-my-codex allows interrupted workflows to resume from the last valid verdict without re-running expensive visual comparisons.

## Practical Implementation Examples

### CLI Invocation

Run the skill directly from the command line to evaluate a screenshot against references:

```bash
omx run $visual-verdict \
  --reference_images=ref-01.png,ref-02.png \
  --generated_screenshot=ui-current.png \
  --category_hint=dashboard

```

Example output when revision is required:

```json
{
  "score": 87,
  "verdict": "revise",
  "category_match": true,
  "differences": [
    "Top nav spacing is tighter than reference",
    "Primary button uses smaller font weight"
  ],
  "suggestions": [
    "Increase nav item horizontal padding by 4px",
    "Set primary button font-weight to 600"
  ],
  "reasoning": "Core layout matches, but style details still diverge."
}

```

### Automated Iteration Loop

Implement the gate logic in Node.js to enforce the 90-point threshold programmatically:

```javascript
import { execSync } from 'node:child_process';
import fs from 'node:fs';
import path from 'node:path';

const scope = 'my-feature';
const verdictPath = `.omx/state/${scope}/ralph-progress.json`;

function runVisualVerdict(refImages, screenshot) {
  const cmd = [
    'omx run $visual-verdict',
    `--reference_images=${refImages.join(',')}`,
    `--generated_screenshot=${screenshot}`,
    '--category_hint=dashboard'
  ].join(' ');
  const out = execSync(cmd, { encoding: 'utf-8' });
  return JSON.parse(out);
}

let score = 0;
while (score < 90) {
  const verdict = runVisualVerdict(['ref-01.png'], 'ui-current.png');
  score = verdict.score;

  // Persist the verdict for Ralph
  fs.mkdirSync(path.dirname(verdictPath), { recursive: true });
  fs.writeFileSync(verdictPath, JSON.stringify(verdict, null, 2));

  if (score >= 90) break;            // pass → exit loop

  // ---- edit UI based on verdict.suggestions ----
  console.log('🔧 Applying suggestions:', verdict.suggestions);
  // (human or automated UI adjustments happen here)
}
console.log('✅ Visual score reached', score);

```

This script respects the visual iteration gate by running the skill first, checking the threshold, and looping until the 90-point requirement is satisfied while maintaining the required state persistence.

## Summary

- The **visual iteration gate** is a hard control point that runs `$visual-verdict` before every code edit on visual tasks.
- The **pass threshold is 90+** on a 0-100 integer scale, with scores below 90 forcing mandatory revision cycles.
- Verdicts must be persisted to `.omx/state/{scope}/ralph-progress.json` for auditability and loop continuity.
- The **Ralph skill** automatically inherits this behavior, requiring visual verification before proceeding with edits.
- The system creates a deterministic, repeatable quality checkpoint that prevents visual regression from entering the codebase.

## Frequently Asked Questions

### What happens if $visual-verdict returns a score below 90?

The visual iteration gate blocks all forward progress. The system requires immediate UI edits based on the `suggestions` array, followed by a mandatory re-run of `$visual-verdict` before any subsequent code changes, commits, or tests are allowed. This cycle repeats until the score reaches 90 or above.

### Where does oh-my-codex store the visual verdict results?

According to the execution protocol in [`AGENTS.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md), the complete verdict JSON—including the numeric score, reasoning, and suggestions—is written to `.omx/state/{scope}/ralph-progress.json`【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/AGENTS.md#L77-L80】. The `{scope}` placeholder represents the current task or feature identifier.

### Is the 90-point threshold configurable in the source code?

The source analysis indicates the 90-point threshold is hardcoded as the pass criterion in [`skills/visual-verdict/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/visual-verdict/SKILL.md)【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/skills/visual-verdict/SKILL.md#L44-L46】. While the skill returns scores across the full 0-100 range, the visual iteration gate specifically requires 90+ to unlock the next development stage.

### How does Ralph integrate with the visual iteration gate?

The Ralph skill explicitly references the gate requirement in its documentation at [`skills/ralph/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/ralph/SKILL.md), stating that developers must *"Run `$visual-verdict` before every next edit"*【/cache/repos/github.com/Yeachan-Heo/oh-my-codex/main/skills/ralph/SKILL.md#L66-L70】. This ensures any workflow orchestrated by Ralph automatically enforces the 90-point visual fidelity checkpoint without additional configuration.