Skip to content

Official Codebase of 3DCodeVerse

Python

references: a photo folder per prompt, and graphics/scene judged for likeness, not silhouette

gaoypengd5d76b7cb70f
diff --git a/harness/bench/refs/README.md b/harness/bench/refs/README.md
new file mode 100644
index 00000000..380cf2dd
--- /dev/null
+++ b/harness/bench/refs/README.md
@@ -0,0 +1,23 @@
+# bench/refs — reference photos per prompt id
+
+One folder per battery prompt id, holding photos of the REAL thing the prompt names:
+
+```
+bench/refs/<prompt_id>/<what_it_shows>.png|jpg|jpeg|webp
+```
+
+`bench/run_bench.py::discover_references` attaches every image in the folder to the prompt's
+`Spec.references` for every bench driver (`3dcv bench run`, `bench/compare_backends.py`,
+`bench/ab_plan.py`), in sorted filename order, with the file stem (underscores → spaces) as the
+note the agent and the judge read. A prompt may also list `references:` paths in its yaml.
+
+* object tracks (static / articulated): the first image is the `target` (silhouette IoU is
+ measured against it, `ReferenceJudge`), the rest are `detail`.
+* graphics / scene: every image is a `likeness` reference — the agent gets the photos on its
+ first message with a note saying to take the physics (dominant colour, structure, where the
+ light sits, how much stays dark), not the composition; the judge is `LikenessJudge` (the same
+ photos beside the frames, no silhouette).
+
+So "with references" vs "without" is the same battery with the folder present or absent.
+Keep photos you have the right to use; name the file by what it shows. First folder:
+`tsr_gfx_aurora_ridge/` (two aurora photographs, 2026-08-26).
diff --git a/harness/bench/refs/tsr_gfx_aurora_ridge/aurora_green_spiral_sea.png b/harness/bench/refs/tsr_gfx_aurora_ridge/aurora_green_spiral_sea.png
new file mode 100644
index 00000000..0af725b8
Binary files /dev/null and b/harness/bench/refs/tsr_gfx_aurora_ridge/aurora_green_spiral_sea.png differ
diff --git a/harness/bench/refs/tsr_gfx_aurora_ridge/aurora_purple_green_lake.png b/harness/bench/refs/tsr_gfx_aurora_ridge/aurora_purple_green_lake.png
new file mode 100644
index 00000000..8075b10a
Binary files /dev/null and b/harness/bench/refs/tsr_gfx_aurora_ridge/aurora_purple_green_lake.png differ
diff --git a/harness/bench/run_bench.py b/harness/bench/run_bench.py
index b3de5733..e915b765 100644
--- a/harness/bench/run_bench.py
+++ b/harness/bench/run_bench.py
@@ -37,7 +37,7 @@ from bench._jsonl import read_jsonl, seal_for_append
from codeverse.config import get_settings
from codeverse.contracts.common import Backends, Budget, Language, Track
from codeverse.contracts.run import RunRecord
-from codeverse.contracts.spec import Constraints, Spec
+from codeverse.contracts.spec import Constraints, ReferenceImage, Spec
from codeverse.cost import run_ledger
from codeverse.workspace import Workspace
@@ -56,6 +56,9 @@ class BenchPrompt(BaseModel):
language: Language | None = Field(
default=None, description="per-prompt override of the battery language "
"(e.g. the opengl_python rows of a glsl_shader battery)")
+ references: list[str] = Field(
+ default_factory=list,
+ description="reference image paths (relative to the battery file); bench/refs/<id>/*.png|jpg are added automatically")
class Battery(BaseModel):
@@ -64,11 +67,12 @@ class Battery(BaseModel):
language: Language
description: str = ""
prompts: list[BenchPrompt] = Field(min_length=1)
+ source_dir: Path | None = Field(default=None, exclude=True, description="directory of the yaml this battery was loaded from")
@classmethod
def load(cls, path: Path | str) -> Battery:
data = yaml.safe_load(Path(path).read_text())
- return cls.model_validate(data)
+ return cls.model_validate(data).model_copy(update={"source_dir": Path(path).resolve().parent})
class BenchItemResult(BaseModel):
@@ -108,6 +112,38 @@ class BenchOptions(BaseModel):
"(the point of `infra_failed`: retry what the weather lost)")
+REFS_DIR = Path(__file__).resolve().parent / "refs"
+REF_SUFFIXES = (".png", ".jpg", ".jpeg", ".webp")
+
+
+def discover_references(item: BenchPrompt, track: Track, *, battery_dir: Path | None = None, refs_dir: Path = REFS_DIR) -> list[ReferenceImage]:
+ """The prompt's reference images: its explicit ``references`` plus ``bench/refs/<id>/*``.
+
+ One folder per prompt id, maintained by hand (photos of the real thing), so an A/B of
+ "with references" against "without" is the same battery with the folder present or
+ absent — nothing else changes. Object tracks get role ``target`` for the first image
+ and ``detail`` for the rest (the silhouette judge matches the target); graphics and
+ scene get ``likeness`` (what the real thing looks like — LikenessJudge, no silhouette).
+ The note is the file stem with underscores as spaces, so a name like
+ ``aurora_green_spiral_sea.png`` tells the agent what it is looking at.
+ """
+ paths: list[Path] = []
+ base = battery_dir or Path.cwd()
+ for rel in item.references:
+ p = Path(rel) if Path(rel).is_absolute() else base / rel
+ if p.is_file():
+ paths.append(p.resolve())
+ folder = refs_dir / item.id
+ if folder.is_dir():
+ paths.extend(sorted(p.resolve() for p in folder.iterdir() if p.suffix.lower() in REF_SUFFIXES and p.is_file()))
+ likeness = track in (Track.GRAPHICS, Track.SCENE)
+ out: list[ReferenceImage] = []
+ for i, p in enumerate(paths):
+ role = "likeness" if likeness else ("target" if i == 0 else "detail")
+ out.append(ReferenceImage(path=str(p), role=role, note=p.stem.replace("_", " ")))
+ return out
+
+
def build_spec(
battery: Battery, item: BenchPrompt, *, backends: Backends, rounds: int, max_usd: float,
max_minutes: float, tag0: str, extra_tags: Sequence[str] = (),
@@ -117,6 +153,7 @@ def build_spec(
return Spec(
id=f"{battery.name}/{item.id}", track=battery.track, language=item.language or battery.language, prompt=item.prompt,
constraints=Constraints(must_have=list(item.must_have), dimensions_m=item.dimensions_m),
+ references=discover_references(item, battery.track, battery_dir=battery.source_dir),
budget=Budget(max_rounds=rounds, max_usd=max_usd, max_minutes=max_minutes),
backends=backends, tags=[tag0, battery.name, item.tier, item.category, *extra_tags, *item.tags],
)
diff --git a/harness/codeverse/judges/reference.py b/harness/codeverse/judges/reference.py
index 794e12ee..c10ffba4 100644
--- a/harness/codeverse/judges/reference.py
+++ b/harness/codeverse/judges/reference.py
@@ -310,5 +310,49 @@ def _plan_part_names(inp: JudgeInput) -> list[str]:
return seen[:40]
+
+LIKENESS_NOTE = (
+ "REAL-WORLD REFERENCE PHOTOS are attached (labelled REAL-WORLD REFERENCE n/N). They are not a "
+ "composition to copy; they are what the thing the brief names ACTUALLY looks like. Score "
+ "brief fidelity, colour/light and richness against them: dominant colour and where the "
+ "secondary colours sit, how the structure folds / layers / thins out, where the brightness "
+ "concentrates and how much of the frame stays dark, what the real texture is at fine scale. A "
+ "frame that ticks every noun in the brief but would never be mistaken for the photographed "
+ "thing (a row of evenly spaced bars standing in for curtains, a flat band standing in for a "
+ "gradient of light, cartoon-saturated colour where the photo is subtle) is a 0.4-0.5 on brief "
+ "fidelity, not a 1.0. Foreground, framing and landscape in the photos are incidental unless "
+ "the brief asks for them."
+)
+
+
+class LikenessJudge(VlmJudge):
+ """``VlmJudge`` + the reference photos of the REAL thing — for tracks with no silhouette.
+
+ ``ReferenceJudge`` is built for objects: it measures a front-view silhouette IoU against
+ the target photo and runs a part-inventory mismatch pass. Neither means anything for a
+ fragment shader or a scene, where a reference photo answers a different question — does
+ this LOOK like the thing? Measured 2026-08-26 (teaser aurora, three versions, flash and
+ codex): every version scored 0.78-0.94 with an empty issues list while none resembled an
+ aurora (a comb of straight teal bars; pink cotton-wool lobes), because the brief is a
+ checklist of nouns and the rubric had nothing to say about likeness. This judge attaches
+ up to three photos beside the frames with :data:`LIKENESS_NOTE` and leaves the rubric alone.
+ """
+
+ name = "likeness"
+
+ def __init__(self, model_id: str | None = None, n_samples: int = 1, temperature: float = 0.2, *,
+ rubric: str | Rubric = "shader_v1", max_refs: int = 3, **kwargs: Any):
+ super().__init__(rubric, model_id, n_samples, temperature, **kwargs)
+ self.max_refs = max(1, int(max_refs))
+
+ def context(self, inp: JudgeInput) -> JudgeContext:
+ if self.rubric.measured_criteria():
+ raise ValueError(f"rubric {self.rubric.name} has measured criteria; LikenessJudge measures nothing")
+ refs = [r for r in inp.spec.references if Path(r.path).is_file()][: self.max_refs]
+ images = [(f"REAL-WORLD REFERENCE {i}/{len(refs)}" + (f" — {r.note}" if r.note else ""), r.path)
+ for i, r in enumerate(refs, 1)]
+ return JudgeContext(extra_text=LIKENESS_NOTE if refs else "", extra_images=images)
+
+
class ReferenceJudgeError(RuntimeError):
"""The reference judge cannot compute its measured criteria."""
diff --git a/harness/codeverse/prompts/tracks/refine_graphics.j2 b/harness/codeverse/prompts/tracks/refine_graphics.j2
index 8b6a8c42..3b5e4c10 100644
--- a/harness/codeverse/prompts/tracks/refine_graphics.j2
+++ b/harness/codeverse/prompts/tracks/refine_graphics.j2
@@ -13,6 +13,9 @@ Files in scope: {% for f in files %}`{{ f }}`{% if not loop.last %}, {% endif %}
## What the judge saw
{{ judge_summary }}
+{% if reference_note %}
+{{ reference_note }}
+{% endif %}
## Frame metrics measured by the harness (t = {{ judge_times }})
{{ frame_notes }}
diff --git a/harness/codeverse/tracks/common.py b/harness/codeverse/tracks/common.py
index e7d9a418..8cb17852 100644
--- a/harness/codeverse/tracks/common.py
+++ b/harness/codeverse/tracks/common.py
@@ -65,6 +65,10 @@ class Services:
"""Image-conditioned judge (spec has reference images): renders + references + silhouette IoU."""
return _import("codeverse.judges.reference", "ReferenceJudge")(model_id=model_id, n_samples=n_samples, rubric=rubric)
+ def likeness_judge(self, model_id: str, n_samples: int = 1, rubric: str = "shader_v1") -> Any:
+ """Reference photos beside the frames, no silhouette (graphics / scene with images)."""
+ return _import("codeverse.judges.reference", "LikenessJudge")(model_id=model_id, n_samples=n_samples, rubric=rubric)
+
def pairwise(self, model_id: str) -> Any:
"""Position-swapped A/B judge: ``.compare(spec, renders_a, renders_b, rubric=...)``."""
return _import("codeverse.judges.pairwise", "PairwiseJudge")(model_id)
diff --git a/harness/codeverse/tracks/graphics.py b/harness/codeverse/tracks/graphics.py
index 84babb07..f081a2a7 100644
--- a/harness/codeverse/tracks/graphics.py
+++ b/harness/codeverse/tracks/graphics.py
@@ -37,7 +37,13 @@ from codeverse.tracks.graphics_steps import (
)
from codeverse.tracks.graphics_steps import plan_example as graphics_plan_example
from codeverse.tracks.lifecycle import BaseTrack
-from codeverse.tracks.prompting import current_files, judge_digest, skeleton_files
+from codeverse.tracks.prompting import (
+ current_files,
+ judge_digest,
+ judged_sheet,
+ reference_images,
+ skeleton_files,
+)
from codeverse.workspace import Workspace
log = logging.getLogger(__name__)
@@ -111,7 +117,7 @@ class GraphicsTrack(BaseTrack):
ctx, skeleton_files=skeleton_files(ctx) if ctx.single_shot else {}, previous_error=""))
ctx.record_prompt("generate", prompt)
return [GenerationTask(label="baseline", prompt=prompt, system=self.system_prompt(ctx), files_hint=files, round=0,
- kind="baseline", temperature=0.6, thinking="medium")]
+ kind="baseline", temperature=0.6, thinking="medium", images=reference_images(ctx))]
def round_files_hint(self, ctx: RunContext) -> list[str]:
return graphics_expected_files(ctx)
@@ -128,4 +134,5 @@ class GraphicsTrack(BaseTrack):
current_files=current_files(ctx, files) if ctx.single_shot else {}))
ctx.record_prompt("refine", prompt)
return GenerationTask(label="refine", prompt=prompt, system=self.system_prompt(ctx), files_hint=files, round=index,
- kind="refine", temperature=0.5, thinking="medium")
+ kind="refine", temperature=0.5, thinking="medium",
+ images=reference_images(ctx) + judged_sheet(last))
diff --git a/harness/codeverse/tracks/lifecycle.py b/harness/codeverse/tracks/lifecycle.py
index 59e98995..ce04204c 100644
--- a/harness/codeverse/tracks/lifecycle.py
+++ b/harness/codeverse/tracks/lifecycle.py
@@ -383,11 +383,13 @@ class BaseTrack:
return n
def make_judge(self, ctx: RunContext, *, n_samples: int | None = None) -> Any:
- """The main judge: injected → reference judge when the spec has images → rubric VLM judge."""
+ """The main judge: injected → reference / likeness judge when the spec has images → rubric VLM judge."""
if self._judge is not None:
return self._judge
n_samples = ctx.policy.judge_samples if n_samples is None else n_samples
if ctx.spec.references:
+ if ctx.track in (Track.GRAPHICS, Track.SCENE): # nothing to silhouette-match: likeness only
+ return self.services.likeness_judge(ctx.spec.backends.judge, n_samples=n_samples, rubric=ctx.rubric)
return self.services.reference_judge(ctx.spec.backends.judge, n_samples=n_samples, rubric=ctx.rubric)
return self.services.judge(ctx.rubric, ctx.spec.backends.judge, n_samples=n_samples)
diff --git a/harness/codeverse/tracks/prompting.py b/harness/codeverse/tracks/prompting.py
index 89150e29..9a78a86e 100644
--- a/harness/codeverse/tracks/prompting.py
+++ b/harness/codeverse/tracks/prompting.py
@@ -14,7 +14,7 @@ from pathlib import Path
from typing import Any
from codeverse.contracts.chat import ImagePart
-from codeverse.contracts.common import Language
+from codeverse.contracts.common import Language, Track
from codeverse.contracts.plan import Plan, StaticPlan
from codeverse.contracts.run import RoundRecord
from codeverse.conventions import LANGUAGE_FRAME, Frame, frame_doc, to_snake
@@ -275,11 +275,37 @@ def judged_sheet(last: Any) -> list[ImagePart]:
]
+def _likeness_note(ctx: RunContext, refs: list[Any]) -> str:
+ """Graphics / scene: the photos say what the REAL thing looks like, not what to compose.
+
+ The object-track note asks for a silhouette match and an IoU tool; a shader has no
+ silhouette. What an aurora / a harbour / a nebula needs from a photo is its physics —
+ dominant colour, how the structure folds and thins, where the light sits, how much of
+ the frame stays dark — and the judge sees the same photos beside the frames.
+ """
+ lines = [
+ f"REFERENCE PHOTOS ({len(refs)}) of the REAL thing are attached. They are not a composition to copy; "
+ "they show what the brief's subject actually looks like: its dominant colour and where the secondary "
+ "colours sit, how its structure folds / layers / thins out, where the brightness concentrates and how "
+ "much of the frame stays dark, its texture at fine scale. Match THAT — it outranks the brief's "
+ "adjectives when the two disagree, and the judge scores your frames beside the same photos. A row of "
+ "evenly spaced bars is not a curtain; a flat band is not a glow; cartoon saturation is not a night sky. "
+ "Take the physics from the photo, not the postcard: foreground, framing and landscape stay as the brief says."
+ ]
+ for i, r in enumerate(refs, 1):
+ lines.append(f"- reference {i}: `{r.path}`" + (f" — {r.note}" if r.note else ""))
+ lines.append("The photos are attached to this message." if ctx.single_shot else
+ "The photos are attached to your first message; look at them again before every `gl_frames` / `scene_views` comparison.")
+ return "\n".join(lines)
+
+
def reference_note(ctx: RunContext) -> str:
"""Prompt paragraph telling the generator how to use the reference images (empty when none)."""
refs = [r for r in ctx.spec.references if Path(r.path).is_file()]
if not refs:
return ""
+ if ctx.track in (Track.GRAPHICS, Track.SCENE):
+ return _likeness_note(ctx, refs)
lines = [
f"REFERENCE IMAGES ({len(refs)}): match their silhouette, proportions and visible details — they "
"outrank the text when the two disagree. A harness measures the front-view outline IoU against the "
diff --git a/harness/codeverse/tracks/scene.py b/harness/codeverse/tracks/scene.py
index 6d93141b..613fb593 100644
--- a/harness/codeverse/tracks/scene.py
+++ b/harness/codeverse/tracks/scene.py
@@ -56,6 +56,7 @@ from codeverse.tracks.prompting import (
current_files,
file_for_target_factory,
judge_digest,
+ reference_images,
)
from codeverse.tracks.repair import format_error_report
from codeverse.tracks.scene_asset_gen import select_assets, single_shot_ctx
@@ -250,7 +251,8 @@ class SceneTrack(BaseTrack):
prompt = render("tracks/scene_env.j2", **self._ctx(gen, recipes=cookbook_sections(gen, ENV_RECIPES)))
ctx.record_prompt("scene_env", prompt)
task = GenerationTask(label="env", prompt=prompt, system=self.system_prompt(ctx), files_hint=["src/env.js"], round=0, kind="env",
- temperature=0.5, timeout_s=ctx.budget.timeout_s(ENV_TIMEOUT_S, floor_s=120))
+ temperature=0.5, timeout_s=ctx.budget.timeout_s(ENV_TIMEOUT_S, floor_s=120),
+ images=reference_images(ctx))
task = self._deliver_skills(gen, "env", [task])[0]
res = generate(ctx.ws, agent_id=gen.agent_id, task=task, agent=gen.agent, model=gen.model, settings=ctx.settings,
budget=ctx.budget, events=ctx.events)
@@ -343,7 +345,7 @@ class SceneTrack(BaseTrack):
prompt = render("tracks/scene_compose.j2", **self._ctx(ctx))
ctx.record_prompt("scene_compose", prompt)
task = GenerationTask(label="compose", prompt=prompt, system=self.system_prompt(ctx), files_hint=["src/scene.js"], round=0,
- kind="compose", temperature=0.4)
+ kind="compose", temperature=0.4, images=reference_images(ctx))
task = self._deliver_skills(ctx, "compose", [task])[0]
res = generate(ctx.ws, agent_id=ctx.agent_id, task=task, agent=ctx.agent, model=ctx.model, settings=ctx.settings,
budget=ctx.budget, events=ctx.events)
diff --git a/harness/tests/compare_bench/test_bench_refs.py b/harness/tests/compare_bench/test_bench_refs.py
new file mode 100644
index 00000000..58ad5ec7
--- /dev/null
+++ b/harness/tests/compare_bench/test_bench_refs.py
@@ -0,0 +1,39 @@
+"""bench/refs/<prompt_id>/ is the reference folder: present → attached, absent → nothing changes."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import yaml
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "bench"))
+from run_bench import Battery, BenchPrompt, discover_references # noqa: E402
+
+from codeverse.contracts.common import Track # noqa: E402
+
+
+def test_folder_images_attach_in_name_order_with_track_roles(tmp_path):
+ refs = tmp_path / "refs" / "tsr_gfx_aurora_ridge"
+ refs.mkdir(parents=True)
+ for name in ("b_green_spiral.png", "a_purple_lake.jpg", "notes.txt"):
+ (refs / name).write_bytes(b"x")
+ item = BenchPrompt(id="tsr_gfx_aurora_ridge", prompt="an aurora", tier="medium")
+ gfx = discover_references(item, Track.GRAPHICS, refs_dir=tmp_path / "refs")
+ assert [Path(r.path).name for r in gfx] == ["a_purple_lake.jpg", "b_green_spiral.png"], "sorted, images only"
+ assert {r.role for r in gfx} == {"likeness"} and gfx[0].note == "a purple lake"
+ obj = discover_references(item, Track.STATIC_OBJECT, refs_dir=tmp_path / "refs")
+ assert [r.role for r in obj] == ["target", "detail"]
+ assert discover_references(BenchPrompt(id="other", prompt="x", tier="easy"), Track.GRAPHICS, refs_dir=tmp_path / "refs") == []
+
+
+def test_explicit_references_resolve_against_the_battery_file(tmp_path):
+ (tmp_path / "pics").mkdir()
+ (tmp_path / "pics" / "ref.png").write_bytes(b"x")
+ y = tmp_path / "b.yaml"
+ y.write_text(yaml.safe_dump({"name": "b", "track": "graphics", "language": "glsl_shader",
+ "prompts": [{"id": "p1", "prompt": "x", "tier": "easy", "references": ["pics/ref.png"]}]}))
+ b = Battery.load(y)
+ assert b.source_dir == tmp_path
+ refs = discover_references(b.prompts[0], b.track, battery_dir=b.source_dir, refs_dir=tmp_path / "none")
+ assert [Path(r.path).name for r in refs] == ["ref.png"] and refs[0].role == "likeness"
diff --git a/harness/tests/judges/test_likeness.py b/harness/tests/judges/test_likeness.py
new file mode 100644
index 00000000..7017bce5
--- /dev/null
+++ b/harness/tests/judges/test_likeness.py
@@ -0,0 +1,37 @@
+"""LikenessJudge: the reference photos ride beside the frames; nothing is silhouette-matched."""
+
+from __future__ import annotations
+
+from codeverse.contracts.common import Language, Track
+from codeverse.contracts.spec import ReferenceImage
+from codeverse.judges.reference import LIKENESS_NOTE, LikenessJudge
+from codeverse.judges.rubrics import load_rubric
+from tests.judges.conftest import FakeChatModel, draw_chair, good_reply, image_parts, make_spec
+
+
+def test_likeness_context_attaches_the_photos_and_the_note(judge_input, tmp_path, cache_dir):
+ """Measured 2026-08-26 (teaser aurora ×3, flash + codex): 0.78–0.94 with empty issues while
+ nothing looked like an aurora — the rubric had no photo to hold the frames against."""
+ ref = tmp_path / "aurora_green_spiral_sea.png"
+ draw_chair(ref)
+ judge_input.spec = make_spec(track=Track.GRAPHICS, language=Language.GLSL_SHADER,
+ references=[ReferenceImage(path=str(ref), role="likeness", note="aurora green spiral sea")])
+ model = FakeChatModel([good_reply(load_rubric("shader_v1"), ["A1", "A2"], 0.8)])
+ j = LikenessJudge("fake:fake-1", rubric="shader_v1", chat_model=model, cache_dir=cache_dir)
+ ctx = j.context(judge_input)
+ assert ctx.extra_images == [("REAL-WORLD REFERENCE 1/1 — aurora green spiral sea", str(ref))]
+ assert ctx.extra_text == LIKENESS_NOTE and "evenly spaced bars" in LIKENESS_NOTE
+ assert ctx.measured_scores == {}, "nothing is measured: a shader has no silhouette"
+ verdict = j.judge(judge_input)
+ assert verdict.overall > 0.7
+ req = model.requests[0]
+ labels = [p.label for p in image_parts(req)]
+ assert labels[0].startswith("REAL-WORLD REFERENCE 1/1"), labels
+ assert "REAL-WORLD REFERENCE PHOTOS are attached" in req.messages[0].parts[0].text
+
+
+def test_no_photos_means_a_plain_judge(judge_input, cache_dir):
+ judge_input.spec = make_spec(track=Track.GRAPHICS, language=Language.GLSL_SHADER)
+ j = LikenessJudge("fake:fake-1", rubric="shader_v1", chat_model=FakeChatModel([good_reply(load_rubric("shader_v1"), ["A1", "A2"], 0.8)]), cache_dir=cache_dir)
+ ctx = j.context(judge_input)
+ assert ctx.extra_images == [] and ctx.extra_text == ""
diff --git a/harness/tests/orchestrator_tracks/test_likeness_routing.py b/harness/tests/orchestrator_tracks/test_likeness_routing.py
new file mode 100644
index 00000000..36938ea0
--- /dev/null
+++ b/harness/tests/orchestrator_tracks/test_likeness_routing.py
@@ -0,0 +1,43 @@
+"""Graphics / scene with reference photos: the agent gets the photos, the judge is the likeness one."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+from codeverse.contracts.common import Track
+from codeverse.contracts.spec import ReferenceImage
+from codeverse.tracks.lifecycle import BaseTrack
+from codeverse.tracks.prompting import reference_note
+
+
+def _ctx(track: Track, refs: list[str], *, single_shot: bool = False) -> SimpleNamespace:
+ spec = SimpleNamespace(references=[ReferenceImage(path=p, role="likeness", note="x") for p in refs],
+ backends=SimpleNamespace(judge="gemini:pro"))
+ return SimpleNamespace(spec=spec, track=track, single_shot=single_shot, rubric="shader_v1",
+ policy=SimpleNamespace(judge_samples=2))
+
+
+def test_graphics_note_asks_for_the_physics_not_a_silhouette(tmp_path):
+ png = tmp_path / "aurora_purple_green_lake.png"
+ png.write_bytes(b"\x89PNG\r\n\x1a\n" + b"\x00" * 16)
+ note = reference_note(_ctx(Track.GRAPHICS, [str(png)]))
+ assert "REFERENCE PHOTOS (1)" in note and "evenly spaced bars is not a curtain" in note
+ assert "IoU" not in note and "compare_silhouette" not in note
+ obj = reference_note(_ctx(Track.STATIC_OBJECT, [str(png)]))
+ assert "IoU" in obj, "object tracks keep the silhouette contract"
+ assert reference_note(_ctx(Track.GRAPHICS, [str(tmp_path / "gone.png")])) == ""
+
+
+def test_make_judge_routes_photos_to_the_likeness_judge():
+ calls: list[tuple[str, str]] = []
+ services = SimpleNamespace(
+ likeness_judge=lambda model, n_samples, rubric: calls.append(("likeness", rubric)) or "L",
+ reference_judge=lambda model, n_samples, rubric: calls.append(("reference", rubric)) or "R",
+ judge=lambda rubric, model, n_samples: calls.append(("plain", rubric)) or "P",
+ )
+ me = SimpleNamespace(_judge=None, services=services)
+ assert BaseTrack.make_judge(me, _ctx(Track.GRAPHICS, ["/x.png"])) == "L"
+ assert BaseTrack.make_judge(me, _ctx(Track.SCENE, ["/x.png"])) == "L"
+ assert BaseTrack.make_judge(me, _ctx(Track.STATIC_OBJECT, ["/x.png"])) == "R"
+ assert BaseTrack.make_judge(me, _ctx(Track.GRAPHICS, [])) == "P"
+ assert calls[0] == ("likeness", "shader_v1")