Official Codebase of 3DCodeVerse
Python
Faster plugin loop: edit-only rule after a file's first write, one 3dcode judge step (git, check, pack, instruction), score repairs trivial judgment deviations, brief under 40 KB, judge agent without host-specific tool names, plan references show the fields models got wrong
gaoypengbf006aa8c5ec
diff --git a/harness/README.md b/harness/README.mdindex aa61025c..cb781032 100644--- a/harness/README.md+++ b/harness/README.md@@ -15,14 +15,15 @@ has a fresh-context judge score it.`c3d-*` craft bundles (parts that touch, bbox contract, repeats, scene lighting / placement /materials / motion, shader traps …).* **Instruments** (`3dcode`, a command-line tool): `init`, `validate-plan`, `build`, `check`- (every gate of the track), `judge-pack`, `score`, and the per-track probes — `measure`,+ (every gate of the track), `judge` (commit + tag + `judge-pack` + the judge's instruction),+ `score`, and the per-track probes — `measure`,`check-contract`, `check-connectivity`, `cross-section`, `render-views`, `render-sheet`,`isolate`, `compare-reference`, `joint-sweep`, `scene-probe`, `check-placement`,`scene-views`, `shader-probe`, `gl-probe`, `gl-frames`. Each prints a verdict, numbers,fix hints and the paths of the PNGs it wrote.-* **Judge** (`agents/3d-judge.md`): a subagent that reads only `judge/rNN/brief.md` + the- images and writes `judgment.json`; `3dcode score` does the arithmetic from the rubric's- weights, penalties, floors and gate caps.+* **Judge** (`agents/3d-judge.md`): a subagent started with the one instruction `3dcode judge`+ prints; it reads only `judge/rNN/brief.md` + the images and writes `judgment.json`; `3dcode+ score` does the arithmetic from the rubric's weights, penalties, floors and gate caps.Everything model-side — writing code, looking at renders, judging — is the host agent's ownmodel and billing. There is no pipeline, no vendor backend, no API key and no cost ledger indiff --git a/harness/agents/3d-judge.md b/harness/agents/3d-judge.mdindex 1f1d58d9..7d680975 100644--- a/harness/agents/3d-judge.md+++ b/harness/agents/3d-judge.md@@ -1,13 +1,8 @@---name: 3d-judge-description: The blind judge of a 3dcodeverse round. Started by the 3dcodeverse workflow with ONE argument, the path of a judge folder (judge/rNN) written by `3dcode judge-pack`; it reads only that folder's brief.md and images, answers exactly the JSON the brief states, and writes it to judgment.json. It never sees the builder's code or reasoning, never scores an overall, and is never given anything but the folder path.+description: The blind judge of a 3dcodeverse round. Started by the 3dcodeverse workflow with the one instruction `3dcode judge` prints, naming the path of a judge folder (judge/rNN); it reads only that folder's brief.md and images, answers exactly the JSON the brief states, writes it to judgment.json and replies `wrote <path>`. It never sees the builder's code or reasoning, never scores an overall, and is never given anything but that instruction.mainAgent: falsesubagent: true-tools:- - Read- - Glob- - read_file- - list_dir---You are the BLIND JUDGE of a 3D-code project: exacting but fair. You were given one folder@@ -25,7 +20,7 @@ moves in a posed tile), trust the images for the visual criteria and report thefact as an issue — never infer "nothing moves" or "part missing" from text alone when thetiles show otherwise.-Work in this order: observe (summary, strengths, issues), answer the defect checklist and the+Work in this order: observe (summary, issues), answer the defect checklist and theacceptance items, and only THEN score the criteria against their anchors.Scoring rules:@@ -52,5 +47,5 @@ Scoring rules:penalties, floors and caps.Output: write the ONE JSON object the brief specifies — every key it lists, no prose outside-it — to `judgment.json` inside the folder you were given, and reply with the single line-`wrote <path>/judgment.json`.+it — to `judgment.json` inside the folder you were given. Your whole reply is then exactly one+line, `wrote <path>`, where `<path>` is that file's absolute path — no other words.diff --git a/harness/codeverse3d/gates.py b/harness/codeverse3d/gates.pyindex f06a562b..a0b5e292 100644--- a/harness/codeverse3d/gates.py+++ b/harness/codeverse3d/gates.py@@ -499,7 +499,7 @@ def asset_gate(ws: Workspace, runtime: Any, plan: ScenePlan, language: Language)elif chk.errors:findings.append(GateFinding(gate=ASSET_GATE, severity=Severity.WARN, target=a.name,message=f"{rel}: " + "; ".join(chk.errors)[:400],- fix_hint=f"rewrite {rel} so the deterministic asset check passes", data=data))+ fix_hint=f"edit {rel} at the fault the message names so the asset check passes", data=data))else:size = f"{chk.size_m[0]:.2f}×{chk.size_m[1]:.2f}×{chk.size_m[2]:.2f} m" if chk.size_m else "size unmeasured"findings.append(GateFinding(gate=ASSET_GATE, severity=Severity.INFO, target=a.name,diff --git a/harness/codeverse3d/judges/prompt_builder.py b/harness/codeverse3d/judges/prompt_builder.pyindex b4468617..c41e820b 100644--- a/harness/codeverse3d/judges/prompt_builder.py+++ b/harness/codeverse3d/judges/prompt_builder.py@@ -1,8 +1,9 @@"""What the judge sees: image prep, montage planning and the brief.``prepare_image`` downscales and labels every image; ``plan_montages`` / ``render_montage`` pack ranked views-into ≤2×2 sheets; ``build_brief`` assembles the judge's text (the role, the rubric as a checklist, the measured-facts, the view rig, the exact JSON to return) for ``judge/rNN/brief.md``.+into ≤2×2 sheets; ``build_brief`` assembles this round's data for ``judge/rNN/brief.md`` (the case: request, plan+digest, acceptance items, measured facts, gate findings, view rig; the rubric; the image list; the JSON shape).+The generic judge rules live in the plugin's ``agents/3d-judge.md``, not here."""from __future__ import annotations@@ -10,6 +11,7 @@ from __future__ import annotationsimport hashlibimport jsonimport math+import typingfrom collections.abc import Sequencefrom dataclasses import dataclassfrom pathlib import Path@@ -22,6 +24,8 @@ from codeverse3d.contracts.artifacts import (RENDER_MODES,GateFinding,GateReport,+ ImprovementItem,+ JudgeIssue,Judgment,Measurement,RenderSet,@@ -45,7 +49,7 @@ from codeverse3d.conventions import (to_authoring_frame,view_key,)-from codeverse3d.judges.rubrics import VETO_PENETRATION_DEPTH_M, Rubric, wire_schema+from codeverse3d.judges.rubrics import VETO_PENETRATION_DEPTH_M, Rubricfrom codeverse3d.proc import unique_tmpfrom codeverse3d.spatial.connectivity import PENETRATION_ERROR_M, PENETRATION_WARN_Mfrom codeverse3d.spatial.measure import measure_summary_table@@ -502,51 +506,23 @@ def render_montage(m: Montage, *, cache_dir: Path | None = None, tile_px: int =return out-def describe_montages(montages: list[Montage]) -> str:- grids = [m for m in montages if not m.is_detail]- details = [m for m in montages if m.is_detail]- lines = [f"- image {i}: {m.title}" for i, m in enumerate(grids, 1)]- lines += [f"- detail crop {i}: {m.title.replace('DETAIL CROP — ', '')}" for i, m in enumerate(details, 1)]- return "\n".join(lines)--#: tracks whose rounds have one canonical GLB the judge slice channel may cutSLICE_TRACKS = ("static_object", "articulated_object")#: rubric for a static object judged against reference images (adds the measured silhouette criterion)REFERENCE_RUBRIC = "reference"-TEXT_BUDGET_CHARS = 24_000+#: agy truncates a file read at 46 080 bytes: a brief is one read+BRIEF_MAX_BYTES = 40_000+#: the gate facts alone never exceed this (long finding lists end in a count)+GATES_MAX_CHARS = 5_000MAX_PX = 1024MONTAGE_TILE_PX = 512SLICE_MAX_PX = 1024-_ROLE = """You are the BLIND JUDGE of a 3D-code project: exacting but fair.-You see only the brief, a plan digest, measured numbers, deterministic gate findings and labelled renders of the result — never the builder's code or reasoning (you read ONLY this brief and the images it lists). Judge what is visible and measured; do not invent faults and do not credit what you cannot see.-Gate findings describe the exported FILE (names, node hierarchy, contacts); the renders show the actual geometry. When they seem to disagree about something VISIBLE (a part moves in a posed tile, a part is present), trust the images for the visual criteria and report the file-level fact as an issue — never infer "nothing moves" or "part missing" from text alone when the tiles show otherwise.-Work in this order: observe (summary, strengths, issues), answer the defect checklist and the acceptance items, and only THEN score the criteria against their anchors.--SCORING RULES-- Score each criterion 0..1 against its anchors (interpolate between anchors). Use the WHOLE range: competent work sits at 0.8+, one clearly visible major defect pulls the affected criterion to ~0.4, broken work sits at 0.1-0.3. Do not compress everything into 0.5-0.7 — a primitive box-stack and a crafted product must be 0.4 apart, not 0.1.-- Every score needs evidence that cites the image and tile (e.g. "MONTAGE 1 top-left (front_right_high): rear leg ends 3 cm above ground; measurement ground_gap 0.03").-- DEFECT CHECKLIST: answer EVERY item with present=true/false. true ONLY when the defect is visible in an image, or a gate finding of severity ERROR / a measurement states it; gate WARNINGS (e.g. a few-mm weld overlap) are informational and never make a defect present. Cite where. These answers drive penalties and caps computed in code, so be literal: do not mark a defect to "be safe", and do not hide one to be kind.-- Do NOT compute an overall or decide pass/fail; `3dcode score` computes the weighted overall, subtracts defect penalties, applies floors and caps.-- Issues: observable defects, most severe first, with target = the part / zone / joint / asset name from the plan digest (or "overall"), a kind, a severity and evidence.-- Improvement plan: at most 6 concrete, imperative instructions for the builder ("rear_leg_left: ends 3 cm above y=0 in the ground-contact crop — extend it to touch the ground"; "seat: measured 62 mm thick against the brief's 25 mm — thin it to the stated size"), priority 1 first, each with a target name from the plan digest and an expected_gain estimate. Give items even for passing work if a named change would raise the score; leave empty only when nothing would.-- Acceptance items: answer verified=true ONLY when the renders or measurements prove the item; otherwise false with what is missing.-- Write ONE JSON object matching the schema at the end of this brief to the judgment file it names; no prose outside it."""---#: end of the DEFECT CHECKLIST scoring-rule bullet in ``_ROLE``; the provenance sentence is appended after it-_DEFECT_BULLET_END = 'do not mark a defect to "be safe", and do not hide one to be kind.'-#: one neutral, defect-agnostic sentence for slice (gate-ERROR) rounds-PROVENANCE_ELICITATION = (- "For each defect you mark present, say where it is visible (MONTAGE n / "- "DETAIL CROP n / slice n) or state that it rests on the measured text alone."-)-def _rubric_block(rubric: Rubric) -> str:- lines = [f"RUBRIC {rubric.name} v{rubric.version} (pass threshold {rubric.pass_threshold:.2f}, for information only)"]+ lines = [f"RUBRIC {rubric.name} v{rubric.version} (pass threshold {rubric.pass_threshold:.2f}; the overall is computed in code "+ "from these weights, penalties, floors and caps — score each criterion 0..1 against its anchors)"]for i, c in enumerate(rubric.criteria, 1):if c.kind == "measured":lines.append(f"{i}. {c.id} (weight {c.weight:.2f}) — MEASURED IN CODE, shown for calibration; do not score it.")@@ -572,16 +548,6 @@ def _rubric_block(rubric: Rubric) -> str:return "\n".join(lines)-def build_system_prompt(rubric: Rubric, *, provenance_elicitation: bool = False) -> str:- """The judge's system prompt; ``provenance_elicitation`` appends :data:`PROVENANCE_ELICITATION` once."""- role = _ROLE- if provenance_elicitation:- if role.count(_DEFECT_BULLET_END) != 1:- raise ValueError("prompt_builder._ROLE: the defect-checklist bullet anchor drifted")- role = role.replace(_DEFECT_BULLET_END, _DEFECT_BULLET_END + " " + PROVENANCE_ELICITATION)- return role + "\n\n" + _rubric_block(rubric)--def _clip(text: str, limit: int) -> str:text = text.strip()return text if len(text) <= limit else text[: limit - 12].rstrip() + " …[clipped]"@@ -978,9 +944,6 @@ RIG_RULES: dict[str, str] = {),"geometry": "The GEOMETRY-ONLY montage shows the same object without materials/lighting: use it for holes, inverted (black) faces, intersections and floating parts; use the SHADED montage for materials and detail.","poses": "POSE tiles show the SAME object with joints moved by the instruments (tile label = joint@value or rest). Judge articulation only from them and the joint table.",- "scene_cams": "Views named overview_* and eye_* are rig cameras fitted to the scene bounds (layout X-ray); every other view is one of the scene's own authored cameras (grade composition/lighting on those); 't=' is the animation time.",- "scene_craft": "On the authored cameras also read the CRAFT of the picture, not only its contents: depth readable for what each shot frames, surfaces that read as the brief's materials rather than one flat colour, variety among repeated elements, the secondary detail the brief's place implies, and distance softened where the brief's weather would soften it — each judged against what THIS place would have, not a fixed recipe. The same camera at two times appears as separate tiles; nothing_moves is answered from the MEASURED MOTION line only, never by comparing tiles.",- "scene_contact": "The high overview_* tiles (overview_front_right / overview_back_left / overview_top) are rendered with the fog removed and room ceilings lifted: a missing roof, lid or haze in them is never a defect. overview_low_front stands at ground level just outside the content, where daylight under a base shows. CONTACT CROP images are diagnostic close-ups cut from an overview tile around a placement finding the gate measured (the label names the asset, the kind and the number): judge the contact they show — base meets ground, part through neighbour — never their composition, lighting or dressing. Every floating / sunken / clipping / scale claim must name its view and its asset.","object": "All views show the same object. Use top + low views for symmetry, footprint and ground contact.",}@@ -997,15 +960,10 @@ def view_rig_section(renders: RenderSet, montages: list[Montage], *, scene: boolbits.append(RIG_RULES["geometry"])if any(m.kind in ("poses", "pose_sheet") for m in montages):bits.append(RIG_RULES["poses"])- if scene:- bits.append(RIG_RULES["scene_cams"])- bits.append(RIG_RULES["scene_craft"])- bits.append(RIG_RULES["scene_contact"])- else:+ if not scene:bits.append(RIG_RULES["object"])if renders.console_errors:bits.append(f"PROBE: {len(renders.console_errors)} console error(s) during rendering, first: {_clip(renders.console_errors[0], 200)}")- bits.append("Images in send order:\n" + describe_montages(montages))return "\n".join(bits)@@ -1073,6 +1031,75 @@ def montage_images(return out, montages+def _literal_values(model: type, field: str) -> tuple[str, ...]:+ return tuple(str(v) for v in typing.get_args(model.model_fields[field].annotation))+++def _bound(model: type, field: str, attr: str) -> float:+ return next(float(getattr(m, attr)) for m in model.model_fields[field].metadata if hasattr(m, attr))+++EVIDENCE = "<MONTAGE k <position> (<view>) / DETAIL CROP k / the measurement that shows it>"+++def judgment_shape(rubric: Rubric, acceptance_ids: list[str], judgment_path: Path) -> str:+ """The JSON the judge writes: a filled example with every criterion / defect / acceptance id, then the enum+ lists and ranges the parser holds it to (``rubrics.repair_judgment`` mends anything smaller)."""+ example = {+ "summary": "<2-4 sentences: what it is, what is right, what is most wrong>",+ "issues": [{"target": "<name from the plan digest, or overall>", "kind": "geometry", "severity": "major",+ "detail": "<what is wrong, observable>", "evidence": EVIDENCE}],+ "defects": {d.id: {"present": False, "evidence": "<evidence>"} for d in rubric.defects},+ "acceptance": {a: {"verified": False, "evidence": "<evidence>"} for a in acceptance_ids},+ "criteria": {c.id: {"score": 0.0, "evidence": "<evidence>"} for c in rubric.visual_criteria()},+ "improvement_plan": [{"target": "<name from the plan digest>", "kind": "geometry",+ "instruction": "<one imperative change and its expected effect>", "priority": 1, "expected_gain": 0.05}],+ }+ if not rubric.defects:+ example.pop("defects")+ if not acceptance_ids:+ example.pop("acceptance")+ lo, hi = int(_bound(ImprovementItem, "priority", "ge")), int(_bound(ImprovementItem, "priority", "le"))+ rules = [+ f"Write ONE JSON object of this shape to `{judgment_path}` (nothing else in the file). Every id shown under "+ "criteria, defects and acceptance must be answered; a criterion the rubric marks MEASURED is not listed and not yours.",+ "- criteria[].score: 0..1 against the anchors; evidence names the image and tile or the measurement.",+ "- defects[].present: true only when an image, a gate ERROR or a measurement shows it (a WARN never does).",+ "- acceptance[].verified: true only when a render or a measurement proves the item.",+ f"- issues[].kind ∈ {', '.join(_literal_values(JudgeIssue, 'kind'))}; severity ∈ {', '.join(_literal_values(JudgeIssue, 'severity'))}; most severe first.",+ f"- improvement_plan: at most {hi} items, priority {lo} first ({lo}..{hi}); kind ∈ {', '.join(_literal_values(ImprovementItem, 'kind'))}; expected_gain 0..1.",+ "- Do not compute an overall or a pass/fail: code does that from the rubric.",+ ]+ return "\n".join(rules) + "\n\n```json\n" + _shape_json(example) + "\n```\n"+++def _shape_json(example: dict) -> str:+ """``json.dumps(indent=1)`` with every id entry of a keyed object on one line (a filled example, not a dump)."""+ lines = ["{"]+ keys = list(example)+ for i, k in enumerate(keys):+ v, comma = example[k], ("," if i < len(keys) - 1 else "")+ if isinstance(v, dict):+ lines.append(f' "{k}": {{')+ items = list(v.items())+ lines += [f' "{id_}": {json.dumps(body, ensure_ascii=False)}' + ("," if j < len(items) - 1 else "")+ for j, (id_, body) in enumerate(items)]+ lines.append(" }" + comma)+ else:+ lines.append(f' "{k}": ' + json.dumps(v, indent=1, ensure_ascii=False).replace("\n", "\n ") + comma)+ lines.append("}")+ return "\n".join(lines)+++def _clip_bytes(text: str, limit: int) -> str:+ """``text`` cut to ``limit`` UTF-8 bytes, ending in the clip mark when cut."""+ if len(text.encode()) <= limit:+ return text+ mark = " …[clipped]"+ body = text.encode()[: max(0, limit - len(mark.encode()))].decode(errors="ignore").rstrip()+ return body + mark++def build_brief(*,spec: Spec,@@ -1092,16 +1119,17 @@ def build_brief(slice_images: Sequence[tuple[str, Path]] = (),judgment_path: Path,) -> str:- """The whole judge brief as Markdown: role + rubric, the measured sections, the view rig, every image with its- label and absolute path (in viewing order), and the exact JSON object to write to ``judgment_path``."""+ """The whole judge brief as Markdown, under :data:`BRIEF_MAX_BYTES`: the case (request, plan digest, acceptance+ items, measurements, gate facts, previous verdict, view rig), the rubric, every image with its label and absolute+ path in viewing order, and the JSON shape to write to ``judgment_path``. The case is what gives way when the+ budget is tight; the rubric, the image list and the shape never do."""is_scene = spec.track.value == "scene"- system = build_system_prompt(rubric, provenance_elicitation=bool(slice_images))sections = [brief_section(spec),("PLAN DIGEST:\n" + _clip(plan_summary(plan, spec.language.value), 5000)) if plan is not None else "PLAN DIGEST: (none)",acceptance_section(list(getattr(plan, "acceptance", None) or [])),measurement_section(measurement),- gates_section(gates, scene=is_scene),+ _clip(gates_section(gates, scene=is_scene), GATES_MAX_CHARS),previous_section(previous, round_index),_clip(extra_context, 2500) if extra_context.strip() else "",_clip(extra_text, 2500) if extra_text.strip() else "",@@ -1110,19 +1138,12 @@ def build_brief(if slice_images:rig = rig + "\n" + slice_rig_section([lbl for lbl, _ in slice_images])sections.append(rig)- text = "\n\n".join(s for s in sections if s)- if len(text) > TEXT_BUDGET_CHARS:- text = _clip(text, TEXT_BUDGET_CHARS)+ case = "\n\n".join(s for s in sections if s)acceptance_ids = [a.id for a in (getattr(plan, "acceptance", None) or [])]- schema = json.dumps(wire_schema(rubric, acceptance_ids), indent=1)listing = "\n".join(f"{i}. {lbl}\n {p}" for i, (lbl, p) in enumerate([*extra_images, *images, *slice_images], 1))- return (- f"# Judge brief — round {round_index}\n\n"- "## Your role\n\n" + system + "\n\n"- "## The case\n\n" + text + "\n\n"- "## Images (open each with your image viewer, in this order)\n\n" + listing + "\n\n"- "## Return exactly this JSON\n\n"- f"Write ONE JSON object matching this schema to `{judgment_path}` (nothing else in the file). Score every "- "criterion with evidence, answer every defect-checklist item and every acceptance item.\n\n"- "```json\n" + schema + "\n```\n"- )+ head = f"# Judge brief — round {round_index}\n\n## The case\n\n"+ tail = ("\n\n## Rubric\n\n" + _rubric_block(rubric)+ + "\n\n## Images (open each with your image viewer, in this order)\n\n" + listing+ + "\n\n## Return exactly this JSON\n\n" + judgment_shape(rubric, acceptance_ids, judgment_path))+ room = BRIEF_MAX_BYTES - len(head.encode()) - len(tail.encode())+ return head + _clip_bytes(case, room) + taildiff --git a/harness/codeverse3d/judges/rubrics.py b/harness/codeverse3d/judges/rubrics.pyindex 0d052253..0a6c553c 100644--- a/harness/codeverse3d/judges/rubrics.py+++ b/harness/codeverse3d/judges/rubrics.py@@ -7,10 +7,12 @@ into a penalty and a cap.from __future__ import annotations+import difflibimport hashlibimport jsonimport reimport statistics+import typingfrom fnmatch import fnmatchfrom functools import lru_cachefrom pathlib import Path@@ -22,7 +24,6 @@ from pydantic import (Field,PrivateAttr,ValidationError,- create_model,field_validator,model_validator,)@@ -264,44 +265,6 @@ class JudgeOutput(BaseModel):return {k: v.verified for k, v in self.acceptance.items()}-def build_wire_model(rubric: Rubric, acceptance_ids: list[str]) -> type[BaseModel]:- """A pydantic model whose ``criteria`` / ``acceptance`` objects have fixed keys (``acc_<i>`` aliased to the id)."""- crit_fields: dict[str, Any] = {- c.id: (CriterionScore, Field(description=f"{c.label}: {c.description.strip()[:200]}"))- for c in rubric.visual_criteria()- }- Criteria = create_model("Criteria", **crit_fields)- # field order = generation order: evidence before scores- fields: dict[str, Any] = {- "summary": (str, Field(description="2-4 sentences: what it is, what is right, what is most wrong")),- "strengths": (list[str], Field(default_factory=list, description="≤ 5 short bullets")),- "issues": (list[JudgeIssue], Field(default_factory=list, description="observable defects, most severe first")),- }- if rubric.defects:- def_fields: dict[str, Any] = {- d.id: (DefectVerdict, Field(description=d.text.strip()[:200])) for d in rubric.defects- }- Defects = create_model("Defects", **def_fields)- fields["defects"] = (Defects, Field(description="binary checklist: one entry per defect id, present=true ONLY when seen"))- if acceptance_ids:- acc_fields: dict[str, Any] = {- f"acc_{i}": (AcceptanceVerdict, Field(alias=aid, description=f"acceptance item {aid}"))- for i, aid in enumerate(acceptance_ids)- }- Acceptance = create_model("Acceptance", **acc_fields)- fields["acceptance"] = (Acceptance, Field(description="one entry per acceptance item id"))- fields["criteria"] = (Criteria, Field(description="one entry per criterion id, scored AFTER the observations above"))- fields["improvement_plan"] = (- list[ImprovementItem],- Field(default_factory=list, description="≤ 6 concrete instructions for the builder, priority 1 first"),- )- return create_model("JudgeReply", **fields)---def wire_schema(rubric: Rubric, acceptance_ids: list[str]) -> dict[str, Any]:- return build_wire_model(rubric, acceptance_ids).model_json_schema(by_alias=True)--def _object(value: Any, what: str) -> dict[str, Any]:if not isinstance(value, dict):raise JudgeParseError(f"{what} is not an object: {type(value).__name__}")@@ -369,6 +332,201 @@ def parse_judge_output(return out+# ===================================================================== repair+def _literal_values(model: type[BaseModel], field: str) -> tuple[str, ...]:+ return tuple(str(v) for v in typing.get_args(model.model_fields[field].annotation))+++def _bounds(model: type[BaseModel], field: str) -> tuple[float, float]:+ meta = model.model_fields[field].metadata+ return (next(float(m.ge) for m in meta if hasattr(m, "ge")), next(float(m.le) for m in meta if hasattr(m, "le")))+++#: an issue kind the improvement enum lacks → the improvement kind the builder acts on+IMPROVEMENT_KIND_FALLBACK = {"detail": "geometry", "proportion": "geometry", "scale": "geometry", "fidelity": "composition"}+SEVERITY_FALLBACK = {"blocking": "critical", "severe": "critical", "high": "major", "medium": "major", "moderate": "major",+ "low": "minor", "trivial": "minor", "cosmetic": "minor"}+#: how alike a misspelt enum value must be to the one it is read as+ENUM_MATCH_CUTOFF = 0.75+_TRUE_WORDS = {"true", "yes", "present", "verified", "1"}+_FALSE_WORDS = {"false", "no", "absent", "unverified", "0", "none", ""}+++def _enum(value: Any, allowed: tuple[str, ...], synonyms: dict[str, str], default: str, where: str,+ repairs: list[str]) -> str:+ """``value`` read as one of ``allowed``: as written, a listed synonym, the closest spelling, else ``default``."""+ text = str(value if value is not None else "").strip().lower().replace("-", "_").replace(" ", "_")+ if text in allowed:+ return text+ if text in synonyms and synonyms[text] in allowed:+ fixed = synonyms[text]+ else:+ close = difflib.get_close_matches(text, allowed, n=1, cutoff=ENUM_MATCH_CUTOFF)+ fixed = close[0] if close else default+ repairs.append(f"{where} {value!r} is not one of {list(allowed)} → read as {fixed!r}")+ return fixed+++def _bool(value: Any, where: str, repairs: list[str]) -> bool | None:+ """A real boolean, a yes/no word or a 0/1 → bool; anything else None."""+ if isinstance(value, bool):+ return value+ text = str(value).strip().lower() if isinstance(value, (str, int, float)) else None+ if text in _TRUE_WORDS or text in _FALSE_WORDS:+ flag = text in _TRUE_WORDS+ repairs.append(f"{where} {value!r} → {str(flag).lower()}")+ return flag+ return None+++def _number(value: Any, lo: float, hi: float, where: str, repairs: list[str], *, percent: bool = False) -> float | None:+ """A number (or a numeric string) clamped to ``lo..hi``; ``percent`` reads 1 < x ≤ 100 as x/100. None when not a number."""+ try:+ x = float(value) if not isinstance(value, bool) else None+ except (TypeError, ValueError):+ x = None+ if x is None or x != x:+ return None+ if percent and 1.0 < x <= 100.0:+ repairs.append(f"{where} {value!r} read as a percentage → {x / 100:.2f}")+ x = x / 100+ if not lo <= x <= hi:+ clamped = min(hi, max(lo, x))+ repairs.append(f"{where} {value!r} is outside {lo:g}..{hi:g} → {clamped:g}")+ x = clamped+ if isinstance(value, str):+ repairs.append(f"{where} {value!r} is a string → {x:g}")+ return x+++def _keyed(section: Any, ids: list[str], flag: str, lo_hi: tuple[float, float] | None, where: str,+ repairs: list[str], missing: list[str], *, required: bool) -> dict[str, dict[str, Any]]:+ """criteria / defects / acceptance: one ``{flag, evidence}`` object per known id; bare values are wrapped, unknown+ ids dropped, absent ids reported as missing (``required``) or left to the parser's default."""+ raw = section if isinstance(section, dict) else {}+ if section is not None and not isinstance(section, dict):+ repairs.append(f"{where} is not an object → ignored")+ out: dict[str, dict[str, Any]] = {}+ for key, value in raw.items():+ if key not in ids:+ repairs.append(f"{where}.{key} is not a known id → dropped")+ continue+ body = dict(value) if isinstance(value, dict) else {flag: value}+ if not isinstance(value, dict):+ repairs.append(f"{where}.{key} was a bare value → wrapped as {{{flag}, evidence}}")+ v = body.get(flag)+ fixed = _number(v, *lo_hi, f"{where}.{key}.{flag}", repairs, percent=True) if lo_hi else _bool(v, f"{where}.{key}.{flag}", repairs)+ if fixed is None:+ missing.append(f"{where}.{key}.{flag}" + (" (a number 0..1)" if lo_hi else " (true or false)"))+ continue+ body[flag] = fixed+ body["evidence"] = str(body.get("evidence") or "")+ out[key] = body+ for key in ids:+ if key not in out and not any(m.startswith(f"{where}.{key}.") for m in missing):+ if required:+ missing.append(f"{where}.{key}")+ else:+ repairs.append(f"{where}.{key} not answered → false")+ return out+++def repair_judgment(payload: Any, rubric: Rubric, acceptance_ids: list[str], *,+ measured_scores: dict[str, float] | None = None) -> tuple[dict[str, Any], list[str], list[str]]:+ """Mend the trivial deviations of a judge's JSON and name what is still missing.++ Returns ``(payload, repairs, missing)``: each repair is one line saying what was read as what; ``missing`` lists+ the keys the judge must add (a criterion score, a defect answer, an acceptance verdict) — those are never+ invented. Enum values are read as the closest allowed one (``IMPROVEMENT_KIND_FALLBACK`` / ``SEVERITY_FALLBACK``+ first), numbers are clamped to their range, bare values are wrapped, unknown keys and ids are dropped.+ """+ repairs: list[str] = []+ missing: list[str] = []+ if not isinstance(payload, dict):+ return {}, repairs, ["the file must hold ONE JSON object"]+ data: dict[str, Any] = {}+ known = ("summary", "strengths", "issues", "defects", "acceptance", "criteria", "improvement_plan")+ for key in payload:+ if key not in known:+ repairs.append(f"{key!r} is not a key of the judgment → dropped")+ if not isinstance(payload.get("summary", ""), str):+ repairs.append("summary is not text → str()")+ data["summary"] = str(payload.get("summary") or "")+ strengths = payload.get("strengths") or []+ data["strengths"] = [str(x) for x in strengths] if isinstance(strengths, list) else []+ score_lo_hi = _bounds(CriterionScore, "score")+ visual_ids = [c.id for c in rubric.visual_criteria()]+ measured_ids = [c.id for c in rubric.measured_criteria() if c.id not in (measured_scores or {})]+ data["criteria"] = _keyed(payload.get("criteria"), visual_ids + measured_ids, "score", score_lo_hi, "criteria",+ repairs, missing, required=True)+ data["defects"] = _keyed(payload.get("defects"), [d.id for d in rubric.defects], "present", None, "defects",+ repairs, missing, required=True)+ data["acceptance"] = _keyed(payload.get("acceptance"), list(acceptance_ids), "verified", None, "acceptance",+ repairs, missing, required=True)+ data["issues"] = _issues(payload.get("issues"), repairs)+ data["improvement_plan"] = _plan(payload.get("improvement_plan"), repairs)+ return data, repairs, missing+++def _issues(raw: Any, repairs: list[str]) -> list[dict[str, Any]]:+ if raw is not None and not isinstance(raw, list):+ repairs.append("issues is not a list → ignored")+ out = []+ for i, item in enumerate(raw if isinstance(raw, list) else []):+ where = f"issues[{i}]"+ if not isinstance(item, dict):+ repairs.append(f"{where} is not an object → dropped")+ continue+ detail = str(item.get("detail") or item.get("instruction") or item.get("text") or item.get("evidence") or "")+ if not detail:+ repairs.append(f"{where} has no detail → dropped")+ continue+ out.append({+ "target": str(item.get("target") or "overall"),+ "kind": _enum(item.get("kind"), _literal_values(JudgeIssue, "kind"), {}, "geometry", f"{where}.kind", repairs),+ "severity": _enum(item.get("severity"), _literal_values(JudgeIssue, "severity"), SEVERITY_FALLBACK, "minor",+ f"{where}.severity", repairs),+ "detail": detail, "evidence": str(item.get("evidence") or ""),+ })+ return out+++def _plan(raw: Any, repairs: list[str]) -> list[dict[str, Any]]:+ if raw is not None and not isinstance(raw, list):+ repairs.append("improvement_plan is not a list → ignored")+ lo, hi = _bounds(ImprovementItem, "priority")+ out = []+ for i, item in enumerate(raw if isinstance(raw, list) else []):+ where = f"improvement_plan[{i}]"+ if not isinstance(item, dict):+ repairs.append(f"{where} is not an object → dropped")+ continue+ instruction = str(item.get("instruction") or item.get("detail") or item.get("text") or "")+ if not instruction:+ repairs.append(f"{where} has no instruction → dropped")+ continue+ priority = _number(item.get("priority"), lo, hi, f"{where}.priority", repairs)+ if priority is None:+ priority = min(hi, float(i + 1))+ repairs.append(f"{where}.priority {item.get('priority')!r} → {int(priority)} (its position)")+ gain = _number(item.get("expected_gain", 0.0), *_bounds(ImprovementItem, "expected_gain"), f"{where}.expected_gain", repairs)+ if gain is None:+ repairs.append(f"{where}.expected_gain {item.get('expected_gain')!r} → 0")+ gain = 0.0+ out.append({+ "target": str(item.get("target") or "overall"),+ "kind": _enum(item.get("kind"), _literal_values(ImprovementItem, "kind"), IMPROVEMENT_KIND_FALLBACK, "geometry",+ f"{where}.kind", repairs),+ "instruction": instruction, "priority": int(round(priority)), "expected_gain": gain,+ })+ return out[:int(hi)] if len(out) <= hi else _cap_plan(out, int(hi), repairs)+++def _cap_plan(items: list[dict[str, Any]], cap: int, repairs: list[str]) -> list[dict[str, Any]]:+ repairs.append(f"improvement_plan has {len(items)} items → the {cap} with the lowest priority numbers kept")+ return sorted(items, key=lambda it: it["priority"])[:cap]++_SEV_RANK = {Severity.INFO: 0, Severity.WARN: 1, Severity.ERROR: 2}@@ -587,8 +745,7 @@ class ScoreBreakdown(BaseModel):n_requested: intsample_errors: list[str] = Field(default_factory=list)rubric_hash: str = ""- judge_prompt_hash: str = Field(default="", description="hash of everything the judge is told that is constant per rubric: "- "role prompt + view-rig rules + wire schema (prompt_builder.judge_prompt_hash)")+ judge_prompt_hash: str = Field(default="", description="hash of everything the judge is told that is constant per rubric")samples: list[dict[str, Any]] = Field(default_factory=list)diff --git a/harness/codeverse3d/spatial/registry.py b/harness/codeverse3d/spatial/registry.pyindex fd3a3fe7..f56bf141 100644--- a/harness/codeverse3d/spatial/registry.py+++ b/harness/codeverse3d/spatial/registry.py@@ -148,4 +148,4 @@ def list_tools(*, track: str = "", language: str = "") -> list[ToolDef]:def _ensure_loaded() -> None:"""Import the modules that register every tool."""import codeverse3d.spatial.tools # noqa: F401 — its @tool decorators fill _REGISTRY- import codeverse3d.workflow # noqa: F401 — init / validate_plan / check / judge_pack / score+ import codeverse3d.workflow # noqa: F401 — init / validate_plan / check / judge / judge_pack / scorediff --git a/harness/codeverse3d/workflow.py b/harness/codeverse3d/workflow.pyindex 92f92f7b..e41519ff 100644--- a/harness/codeverse3d/workflow.py+++ b/harness/codeverse3d/workflow.py@@ -1,9 +1,11 @@-"""The workflow tools: ``init`` · ``validate_plan`` · ``check`` · ``judge_pack`` · ``score``.+"""The workflow tools: ``init`` · ``validate_plan`` · ``check`` · ``judge`` · ``judge_pack`` · ``score``.They tie the instruments to the workspace the host agent works in: ``init`` writes ``spec.json`` and what thelanguage runtime owns, ``validate_plan`` validates and normalises ``plan.json``, ``check`` builds and runs everygate of the track, ``judge_pack`` renders the judged views and writes ``judge/rNN/brief.md`` + images for a-fresh-context judge, ``score`` turns that judge's ``judgment.json`` into the rubric arithmetic.+fresh-context judge, ``judge`` is the one step from code to that judge (check if stale → commit + tag ``rNN`` →+judge-pack → the instruction to hand the judge), ``score`` turns the judge's ``judgment.json`` into the rubric+arithmetic, mending trivial deviations first."""from __future__ import annotations@@ -30,6 +32,7 @@ from codeverse3d.judges.rubrics import (aggregate_samples,load_rubric,parse_judge_output,+ repair_judgment,)from codeverse3d.languages import get_runtimefrom codeverse3d.plan_checks import (@@ -42,7 +45,7 @@ from codeverse3d.plan_checks import (schema_echo,validation_errors,)-from codeverse3d.proc import read_json_or_none+from codeverse3d.proc import read_json_or_none, run_subprocessfrom codeverse3d.spatial.observe import rel_path, text_observationfrom codeverse3d.spatial.registry import NoArgs, Observation, ToolContext, ToolUsageError, toolfrom codeverse3d.spatial.silhouette import compare_silhouette, dimension_conflict, measure_reference@@ -417,9 +420,9 @@ def _slug(label: str) -> str:@tool("judge_pack", NoArgs, "Render the track's judged views (14-view rig + clay + poses / authored cameras + rig / "- "judged frames), compose the montages and crops, and write judge/rNN/: brief.md (the case, the rubric as a "- "checklist, the EXACT JSON to return), the images and pack.json. A fresh-context judge reads ONLY that folder. "- "Requires a `check` of the current src/.", cost_hint="slow")+ "judged frames), compose the montages and crops, and write judge/rNN/: brief.md (the case, the rubric, the image "+ "list, the JSON shape to write), the images and pack.json. A fresh-context judge reads ONLY that folder. "+ "Requires a `check` of the current src/; `3dcode judge` runs it for you.", cost_hint="slow")def judge_pack(ctx: ToolContext, args: NoArgs) -> Observation:ws = ctx.workspacespec = _spec(ctx)@@ -487,10 +490,107 @@ def judge_pack(ctx: ToolContext, args: NoArgs) -> Observation:images=all_images, limit=4000)+# ===================================================================== judge+#: the plugin root (``agents/3d-judge.md`` lives beside the package)+PLUGIN_ROOT = Path(__file__).resolve().parent.parent+GIT_IDENTITY = (("user.name", "3dcodeverse"), ("user.email", "3dcodeverse@localhost"))+#: what a workspace repo never tracks (written to .git/info/exclude, not to a tracked file)+GIT_EXCLUDE = ("artifacts/", "judge/", "node_modules/", "__pycache__/", ".venv/")+GIT_TIMEOUT_S = 120.0+++def _git(ws: Workspace, *args: str, ok_codes: tuple[int, ...] = (0,)) -> str:+ r = run_subprocess(["git", *args], cwd=ws.root, timeout_s=GIT_TIMEOUT_S)+ if r.returncode not in ok_codes:+ raise ToolUsageError(f"git {' '.join(args)} failed ({r.returncode}): {(r.stderr or r.stdout).strip()[:400]}")+ return r.stdout+++def _check_stale(ws: Workspace) -> str:+ """Why the last ``check`` cannot stand for the current src/ (empty when it can)."""+ raw = read_json_or_none(ws.gates_path)+ if raw is None:+ return "no check yet"+ res = CheckResult.model_validate(raw)+ if res.src_hash != ws.src_hash():+ return "src/ changed since the last check"+ if not res.build.ok:+ return "the last check did not build"+ return ""+++def commit_round(ws: Workspace, round_index: int, message: str) -> tuple[str, list[str]]:+ """Commit src/ + plan.json as ``rNN`` (re-tagged on repeat) in the workspace's own repo, creating the repo and+ a local identity when there is none. Returns ``(short sha, what was set up)``."""+ notes: list[str] = []+ if not (ws.root / ".git").exists():+ _git(ws, "init", "-q")+ notes.append("git init")+ exclude = ws.root / ".git" / "info" / "exclude"+ if exclude.parent.is_dir():+ have = exclude.read_text().splitlines() if exclude.is_file() else []+ add = [e for e in GIT_EXCLUDE if e not in have]+ if add:+ exclude.write_text("\n".join([*have, *add]) + "\n")+ for key, value in GIT_IDENTITY:+ if not _git(ws, "config", key, ok_codes=(0, 1)).strip():+ _git(ws, "config", key, value)+ notes.append(f"git config {key} {value}")+ paths = [p for p in ("src", "plan.json") if (ws.root / p).exists()]+ if paths:+ _git(ws, "add", "-A", "--", *paths)+ _git(ws, "commit", "-q", "--allow-empty", "-m", message)+ tag = f"r{round_index:02d}"+ _git(ws, "tag", "-f", tag)+ return _git(ws, "rev-parse", "--short", "HEAD").strip(), notes+++def judge_instruction(out: Path) -> str:+ """The exact text to hand a fresh-context judge subagent for the folder ``out``."""+ agent = PLUGIN_ROOT / "agents" / "3d-judge.md"+ definition = f"at {agent}" if agent.is_file() else "3d-judge"+ return (f"You are the 3d-judge of the 3dcodeverse plugin: read the plugin agent definition {definition} and follow it. "+ f"Judge ONLY the folder {out}: read {out / 'brief.md'} and every image it lists, write {out / JUDGMENT_NAME}, "+ f"then reply with exactly one line: wrote {out / JUDGMENT_NAME}")+++@tool("judge", NoArgs, "One step from code to the judge: make the workspace a git repo (local identity if none), run "+ "`check` when the gates are stale for the current src/, commit src/ + plan.json tagged rNN, run `judge-pack`, "+ "and print the folder plus the exact JUDGE INSTRUCTION for a fresh-context 3d-judge subagent. Then "+ "`3dcode score --round N`.", cost_hint="slow")+def judge(ctx: ToolContext, args: NoArgs) -> Observation:+ ws = ctx.workspace+ spec = _spec(ctx)+ lines: list[str] = []+ stale = _check_stale(ws)+ if stale:+ chk = check(ctx, NoArgs())+ if not chk.numbers.get("build_ok"):+ return Observation(ok=False, failed=chk.failed, text=f"JUDGE STOPPED — check ran ({stale}) and did not build:\n" + chk.text,+ numbers=chk.numbers)+ lines.append(f"check ran ({stale}): {chk.text.splitlines()[0]}")+ else:+ lines.append("check is current for this src/")+ sha, notes = commit_round(ws, ctx.round_index, f"round {ctx.round_index}: {spec.prompt[:72]}")+ lines.append(f"committed {sha} tagged r{ctx.round_index:02d}" + (f" ({'; '.join(notes)})" if notes else ""))+ pack = judge_pack(ctx, NoArgs())+ if pack.failed or not pack.ok:+ return Observation(ok=False, failed=pack.failed, text="\n".join(lines) + "\n" + pack.text, numbers=pack.numbers,+ images=pack.images)+ out = ws.judge_dir(ctx.round_index)+ lines += pack.text.splitlines()[:2]+ lines.append("JUDGE INSTRUCTION: " + judge_instruction(out))+ lines.append(f"next: 3dcode score --round {ctx.round_index}")+ return text_observation(lines, numbers={**pack.numbers, "commit": sha, "tag": f"r{ctx.round_index:02d}",+ "instruction": judge_instruction(out)}, limit=4000)++# ===================================================================== score-@tool("score", NoArgs, "Read judge/rNN/judgment.json (the judge's JSON), parse it strictly, apply the rubric's weights, "+@tool("score", NoArgs, "Read judge/rNN/judgment.json (the judge's JSON), mend trivial deviations (an enum spelt wrong, "+ "a number out of range, a bare value, an unknown key — each printed as `repaired:`), apply the rubric's weights, ""defect penalties, floors and gate caps, write judge/rNN/score.json. Prints overall, PASS/FAIL, the caps and the "- "improvement list for the next round (gate ERRORs first).")+ "improvement list for the next round (gate ERRORs first). A judgment missing a criterion score, a defect answer "+ "or an acceptance verdict is a FAIL that names exactly what to add.")def score(ctx: ToolContext, args: NoArgs) -> Observation:ws = ctx.workspacespec = _spec(ctx)@@ -504,12 +604,25 @@ def score(ctx: ToolContext, args: NoArgs) -> Observation:raise ToolUsageError(f"{jpath} does not exist — the judge has to write it first (see brief.md)")rubric = load_rubric(str(pack["rubric"]))acceptance_ids = [str(a) for a in pack.get("acceptance_ids") or []]+ measured = dict(pack.get("measured_scores") or {})+ again = f"then run `3dcode score --round {ctx.round_index}` again"try:payload = parse_json_lenient(jpath.read_text(errors="replace"))- parsed = parse_judge_output(payload, rubric, acceptance_ids, measured_scores=dict(pack.get("measured_scores") or {}))- except (JsonParseError, JudgeParseError) as e:- return Observation.error(f"judgment.json is not a complete verdict: {e}\n"- f"The judge must write ONE JSON object matching the schema at the end of {out / 'brief.md'}.")+ except JsonParseError as e:+ return text_observation([f"SCORE FAIL — {rel_path(jpath, ws.root)} is not JSON: {e}",+ f"Write ONE JSON object of the shape at the end of {out / 'brief.md'} to {jpath}, {again}."],+ ok=False, numbers={"missing": ["a JSON object"]})+ payload, repairs, missing = repair_judgment(payload, rubric, acceptance_ids, measured_scores=measured)+ repaired = [f"repaired: {r}" for r in repairs]+ if missing:+ return text_observation([f"SCORE FAIL — {rel_path(jpath, ws.root)} is incomplete; add to it:"] + [f"- {m}" for m in missing]+ + repaired + [f"(the shape is at the end of {out / 'brief.md'}; {again})"],+ ok=False, numbers={"missing": missing, "repairs": len(repairs)})+ try:+ parsed = parse_judge_output(payload, rubric, acceptance_ids, measured_scores=measured)+ except JudgeParseError as e:+ return text_observation([f"SCORE FAIL — {rel_path(jpath, ws.root)} does not validate: {e}"] + repaired+ + [f"(the shape is at the end of {out / 'brief.md'}; {again})"], ok=False, numbers={"repairs": len(repairs)})gates = [GateReport.model_validate(g) for g in pack.get("gates") or []]renders = RenderSet.model_validate(pack.get("renders") or {})items = list(getattr(plan, "acceptance", None) or [])@@ -518,7 +631,7 @@ def score(ctx: ToolContext, args: NoArgs) -> Observation:ws.write_json(out / SCORE_NAME, judgment)breakdown = json.loads(judgment.raw)lines = [f"SCORE {judgment.overall:.2f} → {'PASS' if judgment.passed else 'FAIL'} (threshold {rubric.pass_threshold:.2f}; "- f"uncapped {breakdown.get('overall_uncapped', 0):.2f}, defects -{breakdown.get('defect_penalty', 0):.2f})"]+ f"uncapped {breakdown.get('overall_uncapped', 0):.2f}, defects -{breakdown.get('defect_penalty', 0):.2f})"] + repairedlines.append("criteria: " + ", ".join(f"{k} {v:.2f}" for k, v in judgment.scores.items()))present = [d for d, on in (breakdown.get("defects") or {}).items() if on]if present:@@ -549,4 +662,4 @@ def score(ctx: ToolContext, args: NoArgs) -> Observation:return text_observation(lines, ok=judgment.passed,numbers={"overall": judgment.overall, "passed": judgment.passed, "scores": judgment.scores,"defects": present, "caps": [c["rule"] for c in caps], "must_missing": missing,- "n_improvements": len(improve)}, limit=8000)+ "n_improvements": len(improve), "repairs": len(repairs)}, limit=8000)diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.mdindex 72aa435a..995b6f53 100644--- a/harness/docs/ARCHITECTURE.md+++ b/harness/docs/ARCHITECTURE.md@@ -22,7 +22,8 @@ LLM-written **raw executable 3D code** — no SDK layered on the language — fo## 1. Design laws1. **Code is truth; artifacts are derived.** `src/` is the deliverable; every GLB, PNG and- URDF is regenerated from it. Every round is a git commit of `src/`.+ URDF is regenerated from it. Every round is a git commit of `src/`, tagged `rNN` by+ `3dcode judge`.2. **Requirements, never templates.** A skill states what must be true, where, and how it ismeasured — interface, sandbox, thresholds — never a mandated shape or structure the briefdid not ask for; ONE executable interface example per language; no fence over ~12 lines.@@ -94,8 +95,9 @@ python function + argparse subcommand (kebab-case; a list argument is a repeated| `validate-plan` | all | validates `plan.json` against the track's plan model + the deterministic plan checks (placeholder echo, hard quality complaints, acceptance present, fixed-part clash); writes the normalised plan back; FAIL lists each error with its JSON path || `build` | all | lint + build with the language runtime, export, measure; `artifacts/build.json` || `check` | all | build + measure + every gate of the track → `artifacts/gates.json`; the round's verdict |+| `judge --round N` | all | the round's hand-over: makes the workspace a git repo with a local identity if needed, re-runs `check` when the gates are stale, commits `src/` + `plan.json` tagged `rNN`, runs `judge-pack`, prints the folder and the `JUDGE INSTRUCTION:` line the host hands verbatim to a fresh `3d-judge` subagent || `judge-pack --round N` | all | renders the judged views, post-render gates, composes the montages/crops, writes `judge/rNN/brief.md` + images; needs a prior `check` in the same state |-| `score --round N` | all | parses `judge/rNN/judgment.json` strictly, applies weights, penalties, floors and the gate caps from `gates.json` → `score.json`; prints overall, passed, caps, the improvement list |+| `score --round N` | all | parses `judge/rNN/judgment.json`, repairs trivial deviations (saying what it repaired), applies weights, penalties, floors and the gate caps from `gates.json` → `score.json`; prints overall, passed, caps, the improvement list || `measure [--parts]*` | object | bbox / extents, ground gap, per-part size / tris / islands || `check-contract` | object | built GLB vs `plan.json`: missing parts, bbox deltas, overall size, ground contact || `check-connectivity` | object | contact graph: floating parts (with the gap vector), interpenetration, stray islands |@@ -133,8 +135,10 @@ the overview rig; graphics: the frame sheet), composes labelled 2 × 2 montages,`brief.md`: the request, the plan digest, the acceptance items, the measured numbers and gatefacts, the rubric's criteria with anchors, the binary defect checklist with penalties and caps,and the EXACT JSON the judge returns (`criteria`, `summary`, `strengths`, `issues`,-`improvement_plan`, `acceptance`, `defects`). The `3d-judge` agent reads only that folder and-writes `judgment.json`. `score` parses it strictly (`judges/rubrics.py`), fills measured+`improvement_plan`, `acceptance`, `defects`). `judge` wraps it: commit + tag, `judge-pack`,+and the one `JUDGE INSTRUCTION:` line the host hands verbatim to a fresh `3d-judge` subagent,+which reads only that folder, writes `judgment.json` and replies `wrote <path>`. `score`+parses the judgment (repairing a trivial deviation and saying so; `judges/rubrics.py`), fills measuredcriteria from code, applies weights, subtracts defect penalties, applies floors, then the capsfrom `gates.json` (build error 0; floating 0.60; penetration 0.70; contract violation 0.75;an unmet `must` acceptance item 0.60 / 0.70 on graphics; the per-track measured caps), anddiff --git a/harness/skills/3d-lang-glsl-shader/SKILL.md b/harness/skills/3d-lang-glsl-shader/SKILL.mdindex 3ebe6613..4f3f6a18 100644--- a/harness/skills/3d-lang-glsl-shader/SKILL.md+++ b/harness/skills/3d-lang-glsl-shader/SKILL.md@@ -17,7 +17,7 @@ shows them to the judge. Every frame is a pure function of the pixel and absolu## Files```src/shader.frag REQUIRED the image pass (no #version, no uniform/out declarations)-src/common.glsl optional helpers, pasted ABOVE shader.frag (and buffer_a.frag) at build time+src/common.glsl optional helpers AND each layer's function (sky, aurora, terrain …), pasted ABOVE shader.frag (and buffer_a.frag) at build time — shader.frag only composites them and stays shortsrc/buffer_a.frag optional ONE feedback buffer pass, rendered every frame before the image pass```Nothing else is read (another file under `src/` is a lint WARN `stray_file`).diff --git a/harness/skills/3d-lang-opengl-python/SKILL.md b/harness/skills/3d-lang-opengl-python/SKILL.mdindex ac67a54f..ae6506b5 100644--- a/harness/skills/3d-lang-opengl-python/SKILL.md+++ b/harness/skills/3d-lang-opengl-python/SKILL.md@@ -17,7 +17,7 @@ handed. No window, no context creation, no clock of your own.## Files```src/program.py REQUIRED defines setup() and render()-src/*.glsl optional shader sources; read with Path(__file__).with_name("x.glsl").read_text()+src/*.glsl optional shader sources, one file per shader so program.py keeps only the GL plumbing; read with Path(__file__).with_name("x.glsl").read_text()```Only these two globs are delivered; another `src/*.py` is a lint WARN (`stray_file`).`references/interface.md` is the interface, executable.diff --git a/harness/skills/3dcodeverse/SKILL.md b/harness/skills/3dcodeverse/SKILL.mdindex f3d425e7..70649d61 100644--- a/harness/skills/3dcodeverse/SKILL.md+++ b/harness/skills/3dcodeverse/SKILL.md@@ -45,9 +45,10 @@ lists a tool's flags. If `3dcode` is not on PATH, run `<plugin root>/bin/3dcode| `init` | writes `spec.json` (track, language, prompt, must-haves, dims, references, style) and the workspace layout; prints the entry files and the skill to read | once, first || `validate-plan` | is `plan.json` a valid plan for the track — schema, plan checks, the acceptance items derived from `spec.json`; writes the normalised plan back (`scene_blender`: also `src/scene.py`) | after every plan edit, until PASS || `build` | does `src/` lint, build and export; measures the result | after every code edit |-| `check` | build + EVERY gate of the track → `artifacts/gates.json`; PASS/FAIL with each ERROR and its fix — the round's verdict | before judging; every ERROR caps the score |-| `judge-pack --round N` | renders the judged views, composes the montages and crops, writes `judge/rNN/brief.md` + images for a fresh-context judge | after a clean `check`, once per round |-| `score --round N` | the rubric arithmetic on `judgment.json`: overall, passed, caps, the improvement list → `score.json` | after the judge wrote `judgment.json` |+| `check` | build + EVERY gate of the track → `artifacts/gates.json`; PASS/FAIL with each ERROR and its fix — the round's verdict (it subsumes `build`, `check-contract` and `check-connectivity`) | before judging; every ERROR caps the score |+| `judge --round N` | the round's hand-over in one call: commits `src/` + `plan.json` tagged `rNN` (re-running `check` when the gates are stale), runs `judge-pack`, prints the folder and the `JUDGE INSTRUCTION:` line for the judge subagent | after a clean `check`, once per round |+| `judge-pack --round N` | renders the judged views, composes the montages and crops, writes `judge/rNN/brief.md` + images for a fresh-context judge | inside `judge`; alone only to re-pack |+| `score --round N` | the rubric arithmetic on `judgment.json`: overall, passed, caps, the improvement list → `score.json`; repairs a trivial deviation in the judgment and says what it repaired | after the judge replied || `measure` | overall bbox, ground gap, per-part size / triangles / islands in Y-up metres (`--parts`) | when a number, not a picture, answers it || `check-contract` | the built object vs `plan.json`: missing parts, bbox delta per part, overall size, ground contact | object tracks, after every build || `check-connectivity` | the contact graph: floating parts with the gap vector that closes them, interpenetration, stray islands | object tracks, after every build |@@ -82,14 +83,19 @@ judge/rNN/ brief.md + montages (judge-pack), judgment.json (the judge), scorerounds over). The one exception is a camera finding: prefer moving the subject (a zone'splacement, the ground under the eye); when the camera itself must move, edit `cameras[]`only and re-run `3dcode validate-plan` — that is not a re-plan.-* Every round is a commit: `git -C W add -A src public 2>/dev/null; git -C W commit -qm rNN`.## The loop+**Editing rule.** After a file's first write, change it only with the host's edit tool, scoped+to the lines the change needs; a large change is several edits, never a whole-file rewrite.+Keep files small and modular so edits stay local — one part / zone / asset / pass per file, as+the language skill's `## Files` allows. Do not re-read a file you just wrote or edited, and+write nothing while a command or a subagent runs: its result wakes you.+1. **Init.** `3dcode init --workspace W --track T --language L --prompt "..."` with`--must-have "..."` / `--must-not "..."` per hard requirement, `--dims height=0.45` per stateddimension, `--references img.png` per reference image. It prints the entry files and the- skill to read. Then `git -C W init` if the workspace is not a repository.+ skill to read.2. **Plan.** Write `plan.json` by `references/plan-<track>.md` (exact numbers, acceptancechecklist), then `3dcode validate-plan --workspace W` until it prints PASS; FAIL lists eacherror with its JSON path — fix the plan, never argue with the validator.@@ -98,31 +104,33 @@ judge/rNN/ brief.md + montages (judge-pack), judgment.json (the judge), score`3dcode check --workspace W`: every ERROR it lists caps the score, so fix each before judging.Object tracks: the whole object first — every plan part at its box and attached to itsparent before any part gets detail (a part still a ≤ 12-triangle box within 1 mm of its plan- box is a `placeholder_part` ERROR); then detail. Commit `r00`.-4. **Judge.** `3dcode judge-pack --workspace W --round 0` writes `judge/r00/` (requires a `check`- in the current state). The judge is a context that has not seen your work: start a FRESH- subagent with the `3d-judge` agent definition and give it ONLY the folder path — it reads- `brief.md` and the images and writes `judgment.json`. Tell it nothing else: not what you- built, not what you think of it. Only when the host cannot start any fresh context, judge- it yourself as a DEGRADED verdict — a clearly separated step after writing nothing else into- context: open `brief.md`, look at every image, answer exactly its JSON — and mark the round- "self-judged" in your report. Then `3dcode score --workspace W --round 0`: it prints- overall, passed, the caps applied and the improvement list.+ box is a `placeholder_part` ERROR); then detail.+4. **Judge.** `3dcode judge --workspace W --round 0`: it commits and tags `r00`, writes+ `judge/r00/` and prints a line starting `JUDGE INSTRUCTION:`. The judge is a context that+ has not seen your work: start a FRESH subagent with the `3d-judge` agent definition and hand+ it that instruction VERBATIM — nothing else: not what you built, not what you think of it.+ It reads `brief.md` and the images, writes `judgment.json` and replies `wrote <path>`; wait+ for that reply. Only when the host cannot start any fresh context, judge it yourself as a+ DEGRADED verdict — a clearly separated step after writing nothing else into context: open+ `brief.md`, look at every image, answer exactly its JSON — and mark the round "self-judged"+ in your report. Then `3dcode score --workspace W --round 0`: it prints overall, passed,+ the caps applied, what it repaired in the judgment and the improvement list.5. **Refine rounds (r01, r02 …; at most 2 unless the user sets another number).** Each roundmakes exactly the score's improvement list, gate ERRORs first (`[gate/...]` items), as- targeted edits — change the lines a task needs, keep every other part, name and dimension.+ edits under the editing rule, keeping every other part, name and dimension.A placement task changes that part's placement numbers to the plan's centre; a material taskchanges that part's colour / roughness / metalness only; a shape task rebuilds that partalone; on graphics a colour/light task touches palette, exposure and grade only, a motiontask the time terms only — never rewrite unrelated layers or passes. A measured findingthat repeats needs a different change of the thing it measures, not the same edit again; a- judge note that repeats needs a visible change in the named view. Then `check` → commit- `rNN` → `judge-pack --round N` → the judge → `score --round N`.+ judge note that repeats needs a visible change in the named view. Then `check` →+ `judge --round N` → the judge → `score --round N`.6. **Stop** when the rounds are used up, when `score` says passed with an empty improvementlist, or when the overall fell two rounds running. The deliverable is the BEST-scoringround: if the last round is not it, `git -C W checkout rNN -- src` (and `public`) and run- `3dcode check` once more so `artifacts/` matches. Report the round, its overall, the caps- and the paths of its montages.+ `3dcode check` once more so `artifacts/` matches. Report in about ten lines: each round's+ overall and caps, the entry files, the deliverable round and the paths of its montages —+ nothing more.## Quality rules on every track@@ -176,5 +184,5 @@ first. Never finish a round on a broken build.fillet/chamfer falling back to the unrounded solid when the kernel refuses it).* Never import a helper SDK, the plugin's own package or `runtime_js/`; harness-owned modules alanguage skill names inside `src/` (scene_threejs `src/lib/*.js`) are the one exception.-* `judgment.json` is the judge's: never edit it, never give the judge anything but the folder- path, and report a self-judged round as such.+* `judgment.json` is the judge's: never edit it, never give the judge anything but the printed+ `JUDGE INSTRUCTION`, and report a self-judged round as such.diff --git a/harness/skills/3dcodeverse/references/plan-graphics.md b/harness/skills/3dcodeverse/references/plan-graphics.mdindex 07d4b9c6..aa7c3b42 100644--- a/harness/skills/3dcodeverse/references/plan-graphics.md+++ b/harness/skills/3dcodeverse/references/plan-graphics.md@@ -12,19 +12,21 @@ and judged on frames at t = 0, 1, 2.5, 4 and 6 s.1920 × 1080. `duration_s` ≥ 6 (the preview loop; judged times stop at 6 s).4. `passes[]` (at most 6) in draw order: `name` PascalCase, `kind` (`fullscreen` | `geometry` |`postprocess` | `feedback`), `description` — what it draws, the technique by name, the quantities (counts,- sizes as screen fractions, speeds, the style's colours); optional `elements[]` (≤ 8 named- things with their numbers) and `detail_hint`. A fragment shader's pass is a layer composited+ sizes as screen fractions, speeds, the style's colours); optional `elements[]` (≤ 8 plain+ strings, each a named thing with its numbers: `["stars ~2000 points", "3 curtains 0.3 frame tall"]`)+ and `detail_hint`. A fragment shader's pass is a layer compositedinside the one shader; an OpenGL program's may be a real pass (geometry, an FBO). One fieldfilling the frame is the `flat_fill` defect (−0.08) and the 0.1 anchor of `depth_and_detail`(weight 0.16): plan structure at the scales the subject has.-5. `uniforms`: the harness uniforms the effect needs (`u_time`, `u_resolution`, `u_prev` for- feedback, `u_noise`).+5. `uniforms`: the harness uniforms the effect needs, as strings (`["u_time", "u_resolution",+ "u_noise"]`; `u_prev` for feedback).6. `motion`: ONE paragraph — what animates, direction, speed in screen fractions per second orHz, easing, and what stays still. Every request animates unless it says "static image": thelargest mean |Δ| between consecutive judged frames must reach 0.002 or the score caps at 0.5.7. `key_visuals`: the nouns a viewer must recognise.-8. `acceptance`: one item per must-have and per key visual (`how: "visual"`), ids `a1…`;- `must` only for what makes it the wrong effect when absent (an unverified `must` caps at 0.7).+8. `acceptance`: one item per must-have and per key visual, each+ `{"id": "a1", "text": "...", "how": "visual", "priority": "must" | "should"}`; `must` only+ for what makes it the wrong effect when absent (an unverified `must` caps at 0.7).Plan inside the language: a fragment shader has no geometry (everything is a function of thepixel, `u_time` and the two samplers); an OpenGL program may draw meshes, instances and passes.diff --git a/harness/skills/3dcodeverse/references/plan-scene.md b/harness/skills/3dcodeverse/references/plan-scene.mdindex 4374a911..4c919492 100644--- a/harness/skills/3dcodeverse/references/plan-scene.md+++ b/harness/skills/3dcodeverse/references/plan-scene.md@@ -28,7 +28,8 @@ constructions. Realistic scale: people 1.7 m, doors 2.1 m, steps 0.17 m, benchjudged enclosed in glass from every camera, lit through the glazing with the frame'sshadows inside, and what is seen through the glass is the brief's world, never a void or aflat colour.-5. `zones[]`: `name` PascalCase, `bbox` (where that zone may place; neighbours overlap ≤ 1 m —+5. `zones[]`: `name` PascalCase, `bbox` `{"center": [x, y, z], "extents": [w, h, d]}` (where+ that zone may place; neighbours overlap ≤ 1 m —and when built the zones read as ONE continuous place: nothing stops dead at a zone edge,scale and materials agree across them, no zone is left a block-out), `contents[]` (assetnames only), `description` as numbers: what the place is and which cameras see it; the@@ -41,8 +42,8 @@ constructions. Realistic scale: people 1.7 m, doors 2.1 m, steps 0.17 m, bench(`threejs` | `bpy` procedural module; `blender_glb` a hero built as an object and shipped asa GLB, costlier, may carry ONE keyframed motion whose pose at t = 1.5 s differs visibly fromt = 0 — named in its description), `description` with construction numbers and colours,- `approx_size_m` = width × height × depth (the built asset is measured against it — a stone- lantern 0.5 × 1.6 × 0.5, a bench 1.6 × 0.9 × 0.6, a pine 3 × 7 × 3), `instances_hint`. An+ `approx_size_m` `[width, height, depth]` in metres (the built asset is measured against it — a+ stone lantern `[0.5, 1.6, 0.5]`, a bench `[1.6, 0.9, 0.6]`, a pine `[3, 7, 3]`), `instances_hint`. Anasset is judged as a prop at scene distance and is instanced: the description names itssilhouette, the two or three features a person would name and its condition, not close-uphardware; real thickness where the thing has it (a fence is stakes and rails, not a coloured@@ -58,14 +59,15 @@ constructions. Realistic scale: people 1.7 m, doors 2.1 m, steps 0.17 m, bencha scrolling uv/normal at ≥ 0.15 m/s; particles ≥ 0.6 m per 1.5 s; boats/vehicles ≥ 1.5 m ora visible turn; lantern flicker ×0.75–×1.3. Motion the brief names is visible from theestablishing camera.-9. `cameras[]` (1–6): `name` ([A-Za-z0-9_-], a filename), `position`, `look_at`, `fov`- (vertical, 5–150), `purpose` (what the shot is of and what the judge should see in it).+9. `cameras[]` (1–6): `name` ([A-Za-z0-9_-], a filename), `position` and `look_at` as+ `[x, y, z]`, `fov` (vertical, 5–150), `purpose` (what the shot is of and what the judge should see in it).Choose the shot set the place implies — a long vista, a close interior, a walk along astreet, a top-down court. Numbers are used literally: compute them from where the subjectis and how big it is. `cameras[0]` is the establishing shot (≥ 20 % of the frame iscontent, not sky or ground; others ≥ 10 %); every eye ≥ 0.3 m above the ground under it,≥ 0.5 m from any surface, looking at content.-10. `acceptance[]`: one per must-have, plus nothing floating or sunken (`how: "probe"`), the+10. `acceptance[]`, each `{"id": "a1", "text": "...", "how": "visual" | "probe"}`: one per+ must-have, plus nothing floating or sunken (`how: "probe"`), thenamed motion visible (`probe`), no world edge from any camera (`visual`), lighting reads asthe stated time of day (`visual`). On this track `priority` is not yours: `validate-plan`sets every plan item to `should`, and the `must` items — each capping the run at 0.60 when