oh-my-codex 0.7.6 → 0.8.1

package/skills/deep-interview/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: deep-interview
+description: Socratic deep interview with mathematical ambiguity gating before execution
+argument-hint: "<idea or vague description>"
+---
+
+<Purpose>
+Deep Interview implements an Ouroboros-inspired Socratic clarification loop before planning or implementation. It turns vague ideas into explicit specifications by asking targeted questions, scoring ambiguity across weighted dimensions, and gating execution until clarity reaches a configurable threshold.
+</Purpose>
+
+<Use_When>
+- The request is broad, ambiguous, or missing concrete acceptance criteria
+- The user says "deep interview", "interview me", "ask me everything", "don't assume", or "ouroboros"
+- The user wants to avoid misaligned implementation from underspecified requirements
+- You need a requirements artifact before handing off to `ralplan`, `autopilot`, `ralph`, or `team`
+</Use_When>
+
+<Do_Not_Use_When>
+- The request already has concrete file/symbol targets and clear acceptance criteria
+- The user explicitly asks to skip planning/interview and execute immediately
+- The user asks for lightweight brainstorming only (use `plan` instead)
+- A complete PRD/plan already exists and execution should start
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Execution quality is usually bottlenecked by requirement clarity. A single expansion pass often misses hidden assumptions. This workflow applies Socratic pressure + quantitative ambiguity scoring so orchestration modes begin with an explicit, testable spec.
+
+Inspired by Ouroboros (https://github.com/Q00/ouroboros) and adapted for OMX conventions.
+</Why_This_Exists>
+
+<Depth_Profiles>
+- **Quick (`--quick`)**: fast pre-PRD pass; target threshold `<= 0.30`; max rounds 5
+- **Standard (`--standard`, default)**: full requirement interview; target threshold `<= 0.20`; max rounds 12
+- **Deep (`--deep`)**: high-rigor exploration; target threshold `<= 0.15`; max rounds 20
+
+If no flag is provided, use **Standard**.
+</Depth_Profiles>
+
+<Execution_Policy>
+- Ask ONE question per round (never batch)
+- Target the weakest clarity dimension each round
+- Gather codebase facts via `explore` before asking user about internals
+- Always run a preflight context intake before the first interview question
+- In Codex CLI, prefer `request_user_input` when available; if unavailable, fall back to concise plain-text one-question turns
+- Re-score ambiguity after each answer and show progress transparently
+- Do not hand off to execution while ambiguity remains above threshold unless user explicitly opts to proceed with warning
+- Persist mode state for resume safety (`state_write` / `state_read`)
+</Execution_Policy>
+
+<Steps>
+
+## Phase 0: Preflight Context Intake
+
+1. Parse `{{ARGUMENTS}}` and derive a short task slug.
+2. Attempt to load the latest relevant context snapshot from `.omx/context/{slug}-*.md`.
+3. If no snapshot exists, create a minimum context snapshot with:
+   - Task statement
+   - Desired outcome
+   - Known facts/evidence
+   - Constraints
+   - Unknowns/open questions
+   - Likely codebase touchpoints
+4. Save snapshot to `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) and reference it in mode state.
+
+## Phase 1: Initialize
+
+1. Parse `{{ARGUMENTS}}` and depth profile (`--quick|--standard|--deep`).
+2. Detect project context:
+   - Run `explore` to classify **brownfield** (existing codebase target) vs **greenfield**.
+   - For brownfield, collect relevant codebase context before questioning.
+3. Initialize state via `state_write(mode="deep-interview")`:
+
+```json
+{
+  "active": true,
+  "current_phase": "deep-interview",
+  "state": {
+    "interview_id": "<uuid>",
+    "profile": "quick|standard|deep",
+    "type": "greenfield|brownfield",
+    "initial_idea": "<user input>",
+    "rounds": [],
+    "current_ambiguity": 1.0,
+    "threshold": 0.3,
+    "max_rounds": 5,
+    "challenge_modes_used": [],
+    "codebase_context": null,
+    "context_snapshot_path": ".omx/context/<slug>-<timestamp>.md"
+  }
+}
+```
+
+4. Announce kickoff with profile, threshold, and current ambiguity.
+
+## Phase 2: Socratic Interview Loop
+
+Repeat until ambiguity `<= threshold`, user exits with warning, or max rounds reached.
+
+### 2a) Generate next question
+Use:
+- Original idea
+- Prior Q&A rounds
+- Current dimension scores
+- Brownfield context (if any)
+- Activated challenge mode injection (Phase 3)
+
+Target the lowest-scoring dimension:
+- Goal Clarity
+- Constraint Clarity
+- Success Criteria Clarity
+- Context Clarity (brownfield only)
+
+### 2b) Ask the question
+Use structured user-input tooling available in the runtime (`AskUserQuestion` / equivalent) and present:
+
+```
+Round {n} | Target: {weakest_dimension} | Ambiguity: {score}%
+
+{question}
+```
+
+### 2c) Score ambiguity
+Score each dimension in `[0.0, 1.0]` with justification + gap.
+
+Greenfield: `ambiguity = 1 - (goal × 0.40 + constraints × 0.30 + criteria × 0.30)`
+
+Brownfield: `ambiguity = 1 - (goal × 0.35 + constraints × 0.25 + criteria × 0.25 + context × 0.15)`
+
+### 2d) Report progress
+Show weighted breakdown table and next focus dimension.
+
+### 2e) Persist state
+Append round result and updated scores via `state_write`.
+
+### 2f) Round controls
+- Round 3+: allow explicit early exit with risk warning
+- Soft warning at profile midpoint (e.g., round 3/6/10 depending on profile)
+- Hard cap at profile `max_rounds`
+
+## Phase 3: Challenge Modes (assumption stress tests)
+
+Use each mode once when applicable:
+
+- **Contrarian** (round 4+): challenge core assumptions
+- **Simplifier** (round 6+): probe minimal viable scope
+- **Ontologist** (round 8+ and ambiguity > 0.30): ask for essence-level reframing
+
+Track used modes in state to prevent repetition.
+
+## Phase 4: Crystallize Artifacts
+
+When threshold is met (or user exits with warning / hard cap):
+
+1. Write interview transcript summary to:
+   - `.omx/interviews/{slug}-{timestamp}.md`  
+     (kept for ralph PRD compatibility)
+2. Write execution-ready spec to:
+   - `.omx/specs/deep-interview-{slug}.md`
+
+Spec should include:
+- Metadata (profile, rounds, final ambiguity, threshold, context type)
+- Context snapshot reference/path (for ralplan/team reuse)
+- Clarity breakdown table
+- Goal / Constraints / Non-goals
+- Testable acceptance criteria
+- Assumptions exposed + resolutions
+- Technical context findings
+- Full or condensed transcript
+
+## Phase 5: Execution Bridge
+
+Present execution options after artifact generation:
+
+1. **`$ralplan` (Recommended)**
+   - Run consensus refinement on the spec:
+   - `$plan --consensus --direct <spec-path>`
+2. **`$autopilot`**
+   - Use spec as high-clarity execution input
+3. **`$ralph`**
+   - Sequential persistence loop using spec/criteria
+4. **`$team`**
+   - Parallel coordinated execution using shared spec
+5. **Refine further**
+   - Continue interview loop for lower ambiguity
+
+**IMPORTANT:** Deep-interview is a requirements mode. On handoff, invoke the selected skill. **Do NOT implement directly** inside deep-interview.
+
+</Steps>
+
+<Tool_Usage>
+- Use `explore` for codebase fact gathering
+- Use `request_user_input` / structured user-input tool for each interview round when available
+- If structured question tools are unavailable, use plain-text single-question rounds and keep the same stage order
+- Use `state_write` / `state_read` for resumable mode state
+- Read/write context snapshots under `.omx/context/`
+- Save transcript/spec artifacts under `.omx/interviews/` and `.omx/specs/`
+</Tool_Usage>
+
+<Escalation_And_Stop_Conditions>
+- User says stop/cancel/abort -> persist state and stop
+- Ambiguity stalls for 3 rounds (+/- 0.05) -> force Ontologist mode once
+- Max rounds reached -> proceed with explicit residual-risk warning
+- All dimensions >= 0.9 -> allow early crystallization even before max rounds
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Preflight context snapshot exists under `.omx/context/{slug}-{timestamp}.md`
+- [ ] Ambiguity score shown each round
+- [ ] Weakest-dimension targeting used
+- [ ] Challenge modes triggered at thresholds (when applicable)
+- [ ] Transcript written to `.omx/interviews/{slug}-{timestamp}.md`
+- [ ] Spec written to `.omx/specs/deep-interview-{slug}.md`
+- [ ] Handoff options provided (`$ralplan`, `$autopilot`, `$ralph`, `$team`)
+- [ ] No direct implementation performed in this mode
+</Final_Checklist>
+
+<Advanced>
+## Suggested Config (optional)
+
+```toml
+[omx.deepInterview]
+defaultProfile = "standard"
+quickThreshold = 0.30
+standardThreshold = 0.20
+deepThreshold = 0.15
+quickMaxRounds = 5
+standardMaxRounds = 12
+deepMaxRounds = 20
+enableChallengeModes = true
+```
+
+## Resume
+
+If interrupted, rerun `$deep-interview`. Resume from persisted mode state via `state_read(mode="deep-interview")`.
+
+## Recommended 3-Stage Pipeline
+
+```
+deep-interview -> ralplan -> autopilot
+```
+
+- Stage 1 (deep-interview): clarity gate
+- Stage 2 (ralplan): feasibility + architecture gate
+- Stage 3 (autopilot): execution + QA + validation gate
+</Advanced>
+
+Task: {{ARGUMENTS}}

package/skills/omx-setup/SKILL.md

@@ -30,7 +30,7 @@ Supported setup flags (current implementation):
    - else default `user` (safe for CI/tests)
 2. Create directories and persist effective scope
 3. Install prompts, native agent configs, skills, and merge config.toml (scope determines target directories)
-4. Verify required team MCP comm tool exports exist in built `dist/mcp/state-server.js`
+4. Verify Team CLI API interop markers exist in built `dist/cli/team.js`
 5. Generate project-root `./AGENTS.md` from `templates/AGENTS.md` (or skip when existing and no force)
 6. Configure notify hook references and write `./.omx/hud-config.json`
 

package/skills/ralph/SKILL.md

@@ -38,6 +38,18 @@ Complex tasks often fail silently: partial implementations get declared "done",
 </Execution_Policy>
 
 <Steps>
+0. **Pre-context intake (required before planning/execution loop starts)**:
+   - Assemble or load a context snapshot at `.omx/context/{task-slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`).
+   - Minimum snapshot fields:
+     - task statement
+     - desired outcome
+     - known facts/evidence
+     - constraints
+     - unknowns/open questions
+     - likely codebase touchpoints
+   - If an existing relevant snapshot is available, reuse it and record the path in Ralph state.
+   - If request ambiguity is high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` to close critical gaps.
+   - Do not begin Ralph execution work (delegation, implementation, or verification loops) until snapshot grounding exists. If forced to proceed quickly, note explicit risk tradeoffs.
 1. **Review progress**: Check TODO list and any prior iteration state
 2. **Continue from where you left off**: Pick up incomplete tasks
 3. **Delegate in parallel**: Route tasks to specialist agents at appropriate tiers
@@ -45,18 +57,24 @@ Complex tasks often fail silently: partial implementations get declared "done",
    - Standard work: MEDIUM tier (Sonnet) -- "Add error handling to this module"
    - Complex analysis: HIGH tier (Opus) -- "Debug this race condition"
 4. **Run long operations in background**: Builds, installs, test suites use `run_in_background: true`
-5. **Verify completion with fresh evidence**:
+5. **Visual task gate (when screenshot/reference images are present)**:
+   - Run `$visual-verdict` **before every next edit**.
+   - Require structured JSON output: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, `reasoning`.
+   - Persist verdict to `.omx/state/{scope}/ralph-progress.json` including numeric + qualitative feedback.
+   - Default pass threshold: `score >= 90`.
+   - **URL-based cloning tasks**: When the task description contains a target URL (e.g., "clone https://example.com"), invoke `$web-clone` instead of `$visual-verdict`. The web-clone skill handles the full extraction → generation → verification pipeline and uses `$visual-verdict` internally for visual scoring.
+6. **Verify completion with fresh evidence**:
    a. Identify what command proves the task is complete
    b. Run verification (test, build, lint)
    c. Read the output -- confirm it actually passed
    d. Check: zero pending/in_progress TODO items
-6. **Architect verification** (tiered):
+7. **Architect verification** (tiered):
    - <5 files, <100 lines with full tests: STANDARD tier minimum (architect-medium / Sonnet)
    - Standard changes: STANDARD tier (architect-medium / Sonnet)
    - >20 files or security/architectural changes: THOROUGH tier (architect / Opus)
    - Ralph floor: always at least STANDARD, even for small changes
-7. **On approval**: Run `/cancel` to cleanly exit and clean up all state files
-8. **On rejection**: Fix the issues raised, then re-verify at the same tier
+8. **On approval**: Run `/cancel` to cleanly exit and clean up all state files
+9. **On rejection**: Fix the issues raised, then re-verify at the same tier
 </Steps>
 
 <Tool_Usage>
@@ -65,6 +83,7 @@ Complex tasks often fail silently: partial implementations get declared "done",
 - 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
+- Persist context snapshot path in Ralph mode state so later phases and agents share the same grounding context
 </Tool_Usage>
 
 ## State Management
@@ -72,7 +91,7 @@ Complex tasks often fail silently: partial implementations get declared "done",
 Use the `omx_state` MCP server tools (`state_write`, `state_read`, `state_clear`) for Ralph lifecycle state.
 
 - **On start**:
-  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>"})`
+  `state_write({mode: "ralph", active: true, iteration: 1, max_iterations: 10, current_phase: "executing", started_at: "<now>", state: {context_snapshot_path: "<snapshot-path>"}})`
 - **On each iteration**:
   `state_write({mode: "ralph", iteration: <current>, current_phase: "executing"})`
 - **On verification/fix transition**:
@@ -148,12 +167,24 @@ When the user provides the `--prd` flag, initialize a Product Requirements Docum
 ### Detecting PRD Mode
 Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
 
+### Visual Reference Flags (Optional)
+Ralph execution supports visual reference flags for screenshot tasks:
+- Repeatable image inputs: `-i <image-path>` (can be used multiple times)
+- Image directory input: `--images-dir <directory>`
+
+Example:
+`ralph -i refs/hn.png -i refs/hn-item.png --images-dir ./screenshots "match HackerNews layout"`
+
 ### PRD Workflow
-1. Create canonical PRD/progress artifacts:
+1. Run deep-interview in quick mode before creating PRD artifacts:
+   - Execute: `$deep-interview --quick <task>`
+   - Complete a compact requirements pass (context, goals, scope, constraints, validation)
+   - Persist interview output to `.omx/interviews/{slug}-{timestamp}.md`
+2. Create canonical PRD/progress artifacts:
    - PRD: `.omx/plans/prd-{slug}.md`
    - Progress ledger: `.omx/state/{scope}/ralph-progress.json` (session scope when available, else root scope)
-2. Parse the task (everything after `--prd` flag)
-3. Break down into user stories:
+3. Parse the task (everything after `--prd` flag)
+4. Break down into user stories:
 
 ```json
 {
@@ -173,9 +204,9 @@ Check if `{{PROMPT}}` contains `--prd` or `--PRD`.
 }
 ```
 
-4. Initialize canonical progress ledger at `.omx/state/{scope}/ralph-progress.json`
-5. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
-6. Proceed to normal ralph loop using user stories as the task list
+5. Initialize canonical progress ledger at `.omx/state/{scope}/ralph-progress.json`
+6. Guidelines: right-sized stories (one session each), verifiable criteria, independent stories, priority order (foundational work first)
+7. Proceed to normal ralph loop using user stories as the task list
 
 ### Example
 User input: `--prd build a todo app with React and TypeScript`

package/skills/ralplan/SKILL.md

@@ -58,6 +58,23 @@ The consensus workflow:
 
 Follow the Plan skill's full documentation for consensus mode details.
 
+## Pre-context Intake
+
+Before consensus planning or execution handoff, ensure a grounded context snapshot exists:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.omx/context/{slug}-*.md` when available.
+3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before continuing.
+
+Do not hand off to execution modes until this intake is complete; if urgency forces progress, explicitly document the risk tradeoffs.
+
 ## Pre-Execution Gate
 
 ### Why the Gate Exists

package/skills/team/SKILL.md

@@ -5,7 +5,7 @@ description: N coordinated agents on shared task list using tmux-based orchestra
 
 # Team Skill
 
-`$team` is the tmux-based parallel execution mode for OMX. It starts real worker Codex and/or Claude CLI sessions in split panes and coordinates them through `.omx/state/team/...` files plus MCP team tools.
+`$team` is the tmux-based parallel execution mode for OMX. It starts real worker Codex and/or Claude CLI sessions in split panes and coordinates them through `.omx/state/team/...` files plus CLI team interop (`omx team api ...`) and state files.
 
 This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.
 
@@ -70,6 +70,23 @@ tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || tru
 
 If duplicates exist, remove extras before `omx team` to prevent HUD ending up in worker stack.
 
+## Pre-context Intake Gate
+
+Before launching `omx team`, require a grounded context snapshot:
+
+1. Derive a task slug from the request.
+2. Reuse the latest relevant snapshot in `.omx/context/{slug}-*.md` when available.
+3. If none exists, create `.omx/context/{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:
+   - task statement
+   - desired outcome
+   - known facts/evidence
+   - constraints
+   - unknowns/open questions
+   - likely codebase touchpoints
+4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick <task>` before team launch.
+
+Do not start worker panes until this gate is satisfied; if forced to proceed quickly, state explicit scope/risk limitations in the launch report.
+
 ## Current Runtime Behavior (As Implemented)
 
 `omx team` currently performs:
@@ -149,6 +166,23 @@ Follow this exact lifecycle when running `$team`:
 Do not run `shutdown` while workers are actively writing updates unless user explicitly requested abort/cancel.
 Do not treat ad-hoc pane typing as primary control flow when runtime/state evidence is available.
 
+## Message Dispatch Policy (CLI-first, state-first)
+
+To avoid brittle behavior, **message/task delivery must not be driven by ad-hoc tmux typing**.
+
+Required default path:
+
+1. Use `omx team ...` runtime lifecycle commands for orchestration.
+2. Use `omx team api ... --json` for mailbox/task mutations.
+3. Verify delivery via mailbox/state evidence (`mailbox/*.json`, task status, `omx team status`).
+
+Strict rules:
+
+- **MUST NOT** use direct `tmux send-keys` as the primary mechanism to deliver instructions/messages.
+- **MUST NOT** spam Enter/trigger keys without first checking runtime/state evidence.
+- **MUST** prefer durable state writes + runtime dispatch (`dispatch/requests.json`, mailbox, inbox).
+- Direct tmux interaction is **fallback-only** and only after failure checks (for example `worker_notify_failed:<worker>`) or explicit user request (for example “press enter”).
+
 ## Operational Commands
 
 ```bash
@@ -189,6 +223,31 @@ Semantics:
 - `.omx/state/team/<team>/workers/worker-<n>/status.json`
 - `.omx/state/team-leader-nudge.json`
 
+
+## Team Mutation Interop (CLI-first)
+
+Use `omx team api` for machine-readable mutation/reads instead of legacy `team_*` MCP tools.
+
+```bash
+omx team api <operation> --input '{"team_name":"my-team",...}' --json
+```
+
+Examples:
+
+```bash
+omx team api send-message --input '{"team_name":"my-team","from_worker":"worker-1","to_worker":"leader-fixed","body":"ACK"}' --json
+omx team api claim-task --input '{"team_name":"my-team","task_id":"1","worker":"worker-1"}' --json
+omx team api transition-task-status --input '{"team_name":"my-team","task_id":"1","from":"in_progress","to":"completed","claim_token":"<token>"}' --json
+```
+
+`--json` responses include stable metadata for automation:
+- `schema_version`
+- `timestamp`
+- `command`
+- `ok`
+- `operation`
+- `data` or `error`
+
 ## Team + Worker Protocol Notes
 
 Leader-to-worker:
@@ -198,8 +257,8 @@ Leader-to-worker:
 
 Worker-to-leader:
 
-- Send ACK to `leader-fixed` mailbox via `team_send_message`
-- Claim task via state API, execute, update task + status
+- Send ACK to `leader-fixed` mailbox via `omx team api send-message --json`
+- Claim/transition/release task lifecycle via `omx team api <operation> --json`
 
 Task ID rule (critical):
 
@@ -277,10 +336,10 @@ Checks:
 
 1. Worker pane capture shows inbox processing
 2. `.omx/state/team/<team>/mailbox/leader-fixed.json` exists
-3. Worker skill loaded and `team_send_message` called
+3. Worker skill loaded and `omx team api send-message --json` called
 4. Task-id mismatch not blocking worker flow
 
-### Worker logs `team_send_message ENOENT` / `team_update_task ENOENT`
+### Worker logs `omx team api ... ENOENT` (or legacy `team_send_message ENOENT` / `team_update_task ENOENT`)
 
 Meaning:
 - Team state path no longer exists while worker is still running.

package/skills/visual-verdict/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: visual-verdict
+description: Structured visual QA verdict for screenshot-to-reference comparisons
+---
+
+<Purpose>
+Use this skill to compare generated UI screenshots against one or more reference images and return a strict JSON verdict that can drive the next edit iteration.
+</Purpose>
+
+<Use_When>
+- The task includes visual fidelity requirements (layout, spacing, typography, component styling)
+- You have a generated screenshot and at least one reference image
+- You need deterministic pass/fail guidance before continuing edits
+</Use_When>
+
+<Inputs>
+- `reference_images[]` (one or more image paths)
+- `generated_screenshot` (current output image)
+- Optional: `category_hint` (e.g., `hackernews`, `sns-feed`, `dashboard`)
+</Inputs>
+
+<Output_Contract>
+Return **JSON only** with this exact shape:
+
+```json
+{
+  "score": 0,
+  "verdict": "revise",
+  "category_match": false,
+  "differences": ["..."],
+  "suggestions": ["..."],
+  "reasoning": "short explanation"
+}
+```
+
+Rules:
+- `score`: integer 0-100
+- `verdict`: short status (`pass`, `revise`, or `fail`)
+- `category_match`: `true` when the generated screenshot matches the intended UI category/style
+- `differences[]`: concrete visual mismatches (layout, spacing, typography, colors, hierarchy)
+- `suggestions[]`: actionable next edits tied to the differences
+- `reasoning`: 1-2 sentence summary
+
+<Threshold_And_Loop>
+- Target pass threshold is **90+**.
+- If `score < 90`, continue editing and rerun `$visual-verdict` before any further code edits in the next iteration.
+- Persist the verdict in `.omx/state/{scope}/ralph-progress.json` with both:
+  - numeric signal (`score`, threshold pass/fail)
+  - qualitative signal (`reasoning`, `suggestions`, `next_actions`)
+</Threshold_And_Loop>
+
+<Debug_Visualization>
+When mismatch diagnosis is hard:
+1. Keep `$visual-verdict` as the authoritative decision.
+2. Use pixel-level diff tooling (pixel diff / pixelmatch overlay) as a **secondary debug aid** to localize hotspots.
+3. Convert pixel diff hotspots into concrete `differences[]` and `suggestions[]` updates.
+</Debug_Visualization>
+
+<Example>
+```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."
+}
+```
+</Example>