Official Codebase of 3DCodeVerse
Python
docs: SKILLS.md is now the whole story — model, library, routing, telemetry, what the tests caught, and the live discovery table; RELEASE_NOTES grows a per-wave structure
gaoypeng78429633a678
diff --git a/harness/docs/RELEASE_NOTES.md b/harness/docs/RELEASE_NOTES.mdindex a70fd9bf..5c047ff1 100644--- a/harness/docs/RELEASE_NOTES.md+++ b/harness/docs/RELEASE_NOTES.md@@ -1,4 +1,12 @@-# Release notes — stability pass, 2026-08-24+# Release notes++Newest first.++<!-- SKILLS-WAVE -->++---++## Stability pass — 2026-08-24Sign-off for the first release intended to be called **stable**. Five parallel waves huntedthe harness for defects, a sixth verified them, three fixed them, and this pass reconciled,@@ -13,7 +21,7 @@ Python 3.10 clean clone with no credentials.----## 1. What was hunted+### 1. What was huntedSix independent sweeps over the 54 files the parallel waves changed:@@ -40,7 +48,7 @@ Each was then reproduced independently before any fix was written.tracked as CQ-5 (the switch nothing reads); the "all six switches silently accepted"half is not — they are validated and rejected.-### Verified defects by severity+#### Verified defects by severity| Severity | Count | Fixed | Open ||---|---|---|---|@@ -58,13 +66,13 @@ at sign-off). 8 fixed, 1 open. **50 fixed in total.**----## 2. What was fixed+### 2. What was fixedEvery fix below landed with a regression test that was **proved to fail without it** — thesource change stashed, the test run, the change restored. The 24 tests belonging to the wavethat had not yet landed were re-proved against `main` at sign-off, as a batch, after rebasing.-### Crashes (8)+#### Crashes (8)| ID | Defect | Commit ||---|---|---|@@ -78,14 +86,14 @@ that had not yet landed were re-proved against `main` at sign-off, as a batch, aCP-3 and RS-6 were the same defect reported twice.-### Data loss (2)+#### Data loss (2)| ID | Defect | Commit ||---|---|---|| CP-5 | one directory-shaped path in a generation envelope discarded the whole answer instead of skipping the bad block | `0884aa7` || RS-1 | `write_json_atomic` shared one `.tmp` name per path: concurrent writers published truncated JSON and crashed mid-save | `ba428eb` |-### Wrong results (19)+#### Wrong results (19)The gates that decide a score, and the accounting that decides what a run cost.@@ -115,14 +123,14 @@ The gates that decide a score, and the accounting that decides what a run cost.`CQ-3`/`SM-01` and `CP-6`/`RS-8` were each one defect found twice by different sweeps; bothlanded twice and were reconciled at sign-off (§6).-### Hangs (2)+#### Hangs (2)| ID | Defect | Commit ||---|---|---|| CP-4 | `run_subprocess` ignored its own `timeout_s` when the child left a detached descendant holding the pipes — unbounded, on every build and render path | `3ba9532` || PORT-1 | the documented "pure-python subset" pytest line silently re-enabled the live tests: a command-line `-m` **replaces** `addopts`, it does not add to it | `616fa46` |-### Usability (10) and style (1)+#### Usability (10) and style (1)| ID | Defect | Commit ||---|---|---|@@ -137,7 +145,7 @@ landed twice and were reconciled at sign-off (§6).| PORT-7 | the TL;DR install path died with "No module named pip"; pip and venv were missing from the prerequisites | `5c79e09` || PORT-8 | building left an untracked `harness/build/`, and the install docs' test counts were stale | `c3612eb` |-### Found by running the thing, not reading it (9)+#### Found by running the thing, not reading it (9)| ID | Defect | Status ||---|---|---|@@ -162,7 +170,7 @@ gone red on push. The threads are now held at a barrier (`7942926`); no product----## 3. Notable behaviour changes+### 3. Notable behaviour changesThings an operator will notice, beyond a bug no longer happening.@@ -189,11 +197,11 @@ Things an operator will notice, beyond a bug no longer happening.----## 4. Known open+### 4. Known open**One item. No crash, data-loss or wrong-result defect is open.**-### SMOKE4 — `CodingAgent.available()` is a false green light+#### SMOKE4 — `CodingAgent.available()` is a false green light`available()` returned `(True, "ok")` for `agy:gemini-3.7-flash`, which could not launch atall, and for `codex:gpt-5.1-codex`, which the ChatGPT-account backend rejects with@@ -222,7 +230,7 @@ first-cell `HTTP 400 model is not supported` as a configuration error, not a scopreflight that runs one trivial turn per CLI arm and classifies a backend model rejection asa config error; and narrowing `available()`'s docstring to what it actually verifies.-### Pre-existing flakes (not from this pass, not fixed)+#### Pre-existing flakes (not from this pass, not fixed)`tests/orchestrator_tracks/test_cost_latency.py::test_a_model_outage_escalates_the_asset_instead_of_losing_it`and `tests/orchestrator_tracks/test_prompts_assets.py::test_scene_templates_render_and_asset_stage_with_blender`@@ -232,12 +240,12 @@ run reported here. Worth a separate look at their fan-out / ordering assumptions----## 5. The claude-code arms, and Sonnet 5+### 5. The claude-code arms, and Sonnet 5Two defects here, both fixed, both affecting **recorded cost and model attribution** ratherthan generated artifacts.-### CC-1 — every `--model` ALIAS recorded the wrong model+#### CC-1 — every `--model` ALIAS recorded the wrong model`claude -p` bills **two** models per session: the work model, plus a small background modelthe CLI uses for its own housekeeping. claude 2.1.243 lists the **auxiliary** one first in@@ -270,7 +278,7 @@ Verified live at sign-off:| `claude-code:opus` | `claude-haiku-4-5-20251001` | `claude-opus-5` | exact || default (no `--model`) | `claude-haiku-4-5-20251001` | `claude-opus-5[1m]` | exact |-### CC-2 — the default arm's model had no price+#### CC-2 — the default arm's model had no price`claude-opus-5[1m]` is the 1M-context Opus 5 variant the **default** claude-code arm serves.`[1m]` is not a version suffix, so it cannot prefix-match `claude-opus-5`, and the id had no@@ -290,7 +298,7 @@ Opus 5 rates with the 1h cache write at 2× input (not modelled, as for every otrow). A test pins that a bracketed suffix still cannot borrow a sibling's price:`claude-sonnet-5[1m]` stays `unknown`.-### Sonnet 5 pricing — checked, and correct+#### Sonnet 5 pricing — checked, and correctThe `claude-sonnet-5` row is `$2.00 / $10.00` per 1M (cached `$0.20`, cache write `$2.50`).This was re-verified at sign-off against the live model documentation on 2026-08-24, because@@ -301,14 +309,14 @@ provenance note ("the launch rate became the standard rate; the 2026-09-01 increcancelled") are right, and no 1 September repricing is pending. Opus 5 confirmed at $5 / $25and Haiku 4.5 at $1 / $5 on the same check.-### Still true about the CLI arms+#### Still true about the CLI arms`codex:gpt-5.1-codex` is rejected by a ChatGPT-account backend; the tiers this repo runs are`gpt-5.6-sol` / `-terra` / `-luna`. `available()` will not warn you (§4).----## 6. Reconciliation notes for reviewers+### 6. Reconciliation notes for reviewersThree things worth knowing about how this landed.@@ -342,9 +350,9 @@ Three things worth knowing about how this landed.----## 7. Verification+### 7. Verification-### Test suite+#### Test suite| Run | Interpreter | Command | Result ||---|---|---|---|@@ -355,7 +363,7 @@ Three things worth knowing about how this landed.The deselected are `live`; **no live test was run and no provider was billed by the suite.**The skips are data-dependent (recorded runs a fresh clone does not have).-### Clean clone+#### Clean clone`git clone` → fresh `python3.10 -m venv` → `pip install -e harness` → `3dcv doctor` →offline subset. Python **3.10.21**, the `requires-python` floor.@@ -370,7 +378,7 @@ offline subset. Python **3.10.21**, the `requires-python` floor.- offline subset: green, with **no credentials in the environment**, which is what a CIrunner has (PORT-2).-### Smoke matrix+#### Smoke matrix55 cells. **47 ok, 0 failed, 8 skipped.** All four cells that failed on the hunt werere-run at sign-off and now pass; the remaining 43 ok cells are carried forward from the hunt@@ -443,7 +451,7 @@ the fix or sign-off passes called a model except the four subscription-CLI probeSign-off re-runs of rows 15, 19, 26 and 52 used four subscription-CLI or offline calls anddid not touch the Gemini key pool.-### House rules+#### House rules- All work done in `git worktree`s; the main tree was never edited while a battery wasrunning, and `git -C /home/yipeng/3dcodeverse status --short` is empty at this commit.diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.mdindex 7b3fec47..37b7f245 100644--- a/harness/docs/SKILLS.md+++ b/harness/docs/SKILLS.md@@ -1,98 +1,271 @@-# Skills — the authoring contract+# SkillsA **skill** is a task-scoped rule sheet the harness attaches to a coding session-automatically, from the track, the language, the round kind, the plan, and **the previous-round's gate findings**. It is not a renamed cookbook chapter: the cookbook-(`codeverse/prompts/<lang>/cookbook.md`) stays the reference manual with the copyable-code; a skill states rules and numbers and names the cookbook section to fetch.+automatically — from the track, the language, the round kind, the plan, and **the previous+round's gate findings**. Nobody writes `skills: [...]`.-`SKILL.md` is an open standard (agentskills.io), which is why the format below is not-ours to bend: claude-code, codex, gemini-cli and agy discover these bundles themselves.-Only `api-agent` needs harness-side injection.+It is not a renamed cookbook chapter. The cookbook (`codeverse/prompts/<lang>/cookbook.md`)+stays the reference manual with the copyable code; a skill states rules and numbers and+names the cookbook section to fetch. Two libraries of truth would be worse than one.-Everything is behind `CV3D_SKILLS` (default **off**). See `codeverse/skills/config.py`.+`SKILL.md` is an open standard (agentskills.io, Dec 2025), which is why the format below is+not ours to bend: **claude-code, codex, gemini-cli and agy discover these bundles+themselves** — proven live, see §7. Only `api-agent` needs harness-side injection.-## 1. Layout+Everything is behind `CV3D_SKILLS`. **It ships OFF.** §6 says why, with the numbers.-```-codeverse/skills/<name>/SKILL.md the bundle (package data — it ships in the wheel)-codeverse/skills/<name>/references/*.md depth: worked examples, long tables. ONE level.-codeverse/skills/_claims/<name>.toml numbers pinned to live constants (outside the bundle)-```+---++## 1. The model: progressive disclosure, and why it is also the measurement++The spec's three tiers, and what each costs us per turn:++| tier | what the agent sees | when | our cost |+|---|---|---|---|+| 1 · index | `name` + one clause of `description` | every turn | 41 tokens (native CLIs) / ≤ 400 (api-agent) |+| 2 · body | the whole `SKILL.md` | on activation | 1,081–2,223 tokens, once |+| 3 · depth | `references/*.md` | when the agent chooses to go deeper | as read |++The same three tiers are the read probe. `materialize_skills` writes every file with+`atime == mtime`; the root filesystem is ext4 with `relatime`, so the first read afterwards+bumps `atime`. A CLI's discovery scan opens `SKILL.md` to read the frontmatter — verified,+§7 — and nothing scans `references/`. So:-`references/` is not optional decoration. Nothing scans it, so an `atime` bump there is-the only honest evidence that an agent read the body rather than a discovery scan reading-the frontmatter. A bundle without it reports `deep_measurable: false` and can never score-on the read metric.+* `atime(SKILL.md) > mtime` → **surfaced**: the bundle reached the agent's index.+* `atime(references/*.md) > mtime` → **deep**: the agent read the body and followed it.-## 2. Frontmatter+A bundle with no `references/` reports `deep_measurable: false` rather than quietly+scoring 0. `api-agent` owns its own `read_file`, so it logs exact reads with turn numbers+and is the **calibration arm** for the probe.++`references/` is therefore not optional decoration. It is the only honest evidence that a+skill was read rather than merely listed.-```yaml----name: cv3d-part-contact # == the directory name, lowercase a-z0-9 and '-', <= 64-description: >- # 1-1024 chars, and it must say WHAT and WHEN- ... the only text a CLI indexes ...-license: Apache-2.0-metadata: # string -> string only- evidence: measured # measured | mixed | inherited-unverified- verified: 2026-08-25 # ISO date the claims were last checked against this repo- corpus: static_v2_flash n=47 # optional, when the body quotes corpus statistics++## 2. The library++Fourteen bundles. `lines`/`tokens` are the body, against caps of 350 and 2,500.++| skill | track | language | evidence | lines | tokens | routes |+|---|---|---|---|---|---|---|+| `cv3d-part-contact` | object tracks | any | measured | 125 | 1,707 | R1, R2 |+| `cv3d-bbox-contract` | object + scene | any | measured | 75 | 1,081 | R3, R4 |+| `cv3d-form-manifest` | object tracks | any | measured | 155 | 1,917 | R5 |+| `cv3d-repeats-and-mirrors` | object tracks | any | measured | 112 | 1,527 | R6, R7 |+| `cv3d-blender-forms` | any | blender, urdf_blender | measured | 97 | 1,809 | R8, R9 |+| `cv3d-urdf-joints` | articulated_object | urdf_blender | measured | 139 | 1,989 | R12, R13 |+| `cv3d-scene-composition` | scene | scene_threejs | mixed | 118 | 1,691 | R14, R15 |+| `cv3d-scene-lighting` | scene | scene_threejs | mixed | 86 | 1,210 | R16, R17 |+| `cv3d-scene-motion` | scene | scene_threejs | mixed | 178 | 2,223 | R18, R19 |+| `cv3d-threejs-shader-traps` | scene + static | threejs both | mixed | 112 | 1,734 | R20, R21 |+| `cv3d-glsl-craft` | graphics | glsl_shader | mixed | 140 | 1,958 | R22, R24-glsl |+| `cv3d-opengl-pipeline` | graphics | opengl_python | mixed | 98 | 1,497 | R23, R24-opengl |+| `cv3d-cadquery-forms` | any | cadquery | **inherited-unverified** | 82 | 1,470 | R10 |+| `cv3d-threejs-forms` | static_object | threejs | **inherited-unverified** | 120 | 1,934 | R11 |++`evidence` is a claim about **n**, and `tests/skills/test_corpus.py` recomputes it from+`bench/out`:++* `measured` — the routed language has ≥ 20 graded runs behind it (blender 139,+ urdf_blender 23 as of 2026-08-25).+* `mixed` — real data, thin (glsl_shader 9, opengl_python 5, scene_threejs 3). Owes an+ `evidence_note` saying so.+* `inherited-unverified` — **zero** graded runs (cadquery, threejs). **Not routed** unless+ `CV3D_SKILLS_UNVERIFIED=on`. The rule that produced this label caught a real over-claim:+ `cv3d-opengl-pipeline` shipped as `measured` on n=5 and is now `mixed`.+----```-Hard rules the loader enforces (`codeverse/skills/loader.py`):--* `name` equals the parent directory name — every discovery implementation keys off it.-* **No `<` or `>` anywhere in the frontmatter.** The spec's prompt-injection rule.-* Only spec keys at the top level; our own fields live under `metadata`.-* Body <= **350 lines** and <= **2,500 estimated tokens** (half the spec's recommendation,- because docs/COST.md §4 shows we pay for every prompt byte on every turn, not once).-* A bundle labelled `inherited-unverified` is **not routed** unless- `CV3D_SKILLS_UNVERIFIED=on`. Today that is cadquery and threejs: zero graded runs each.--## 3. Body rules (enforced by `tests/skills/test_library.py`)--* No code fence longer than 20 lines — code belongs in the cookbook, one library of truth.-* Never restate a frame, unit or naming rule; `codeverse/conventions.py` is the only place- those exist, and two truths are worse than one.-* Every number that came from a live constant gets a `_claims` row, so moving the constant- breaks the test that ships the skill quoting it.-* Every corpus percentage carries its battery, its n and its date.-* Two skills that can be attached to the same session may not disagree about a claim key.--A claim row:--```toml-[[claim]]-key = "penetration_error_m"-text = "10 mm" # must appear in the body-python = "codeverse.spatial.connectivity:PENETRATION_ERROR_M"-scale = 1000-format = "{:.0f} mm"-```+## 3. Routing++`codeverse/skills/registry.py` holds the typed table (R1–R24) and `finding_kind()`, the one+place a gate message is pattern-matched. `codeverse/skills/router.py` turns+`(track, language, kind, plan signals, findings)` into a ranked, capped, reasoned set.++Four laws, all tested:-## 4. Routing+1. **Gate findings outrank everything.** A row that answers a finding sits at priority+ ≥ 90; standing rows sit at ≤ 80. A repair round spends its budget on what broke. This is+ the input no CLI's own skill loader can see, and the reason we route in code.+2. **The cap is 5** (`CV3D_SKILLS_MAX`). It cuts the low-priority tail, never the+ gate-fired head.+3. **Quiet kinds attach nothing** on their own — `asset`, `asset_fix`, `reference` are+ short, narrow sessions with no defect class attached to them. A gate-fired row still+ reaches them (R13/R15/R17/R19/R21 are kind-agnostic; R2/R4/R7/R9 are not — both halves+ are pinned in `test_router`).+4. **Unknown input degrades to `[]`, never an exception.** A planner failure must not also+ take out the round's skills.-Nobody writes `skills: [...]`. `codeverse/skills/registry.py` holds the typed route table-(R1-R24) and `finding_kind()`, the one place a gate message is pattern-matched.-`codeverse/skills/router.py` turns `(track, language, kind, plan signals, findings)` into a-ranked, capped set with a reason per selection. Gate-fired rows (priority >= 90) always-outrank standing rows, so a repair round spends its budget on what actually broke, and at-most `CV3D_SKILLS_MAX` (default 5) bundles are attached.+`test_routing_property.py` runs all of that over the real library and the whole input+space: every track × language × round kind × 64 plan-signal combinations (5,376 sessions+per track), every gate finding kind the corpus produces, and 2,000 seeded random walks+including junk tracks and languages.-Adding a bundle means adding its rows to that table in the same commit — an unroutable-bundle pays the index and never helps, and a test fails on both halves of that.+`finding_kind()` classifies **wider** than it routes — 113 distinct WARN/ERROR message+shapes mined from `bench/out`, with a 43-row golden fixture+(`tests/skills/data/gate_findings.json`) asserting no `unknown`. Naming a defect costs+nothing; routing one is a claim that a skill helps. INFO findings are census, not defects,+and classify to `None` — routing off "all 7 parts are connected" would attach the+interpenetration sheet to a run with no interpenetration.++Adding a bundle means adding its rows in the same commit: an unroutable bundle pays the+index and never helps, and a test fails on both halves of that.++----## 5. Commands+## 4. Telemetry++Per round, `RoundRecord.skills` carries a `SkillsUsage`: what was listed, what was+surfaced, what was read deep, `index_tokens`, `body_tokens_read`. Each attached body's hash+goes into `record.prompt_hashes` as `skill:<name>`, so "what text decided this run" stays+answerable. Per session, `telemetry/skills.jsonl` gets one line.```-3dcv skills list --routes-3dcv skills show cv3d-part-contact-3dcv skills validate-3dcv skills report bench/out/static_v2_flash-3dcv doctor --skills+3dcv skills report bench/out/<battery> # deep-read rate per skill per backend+3dcv skills report bench/out/<battery> --json+3dcv doctor --skills # library + discovery wiring```-`report` is the one that matters: deep-read rate per skill per backend. Targets are->= 60% for CLI backends and >= 80% for api-agent, and a skill under 20% over 20 sessions-is merged or deleted. A library that only ever grows is how this ends as bloat.+Targets: ≥ 60% deep-read for CLI backends, ≥ 80% for api-agent. **A skill under 20% over 20+sessions is merged or deleted.** A library that only ever grows is how this ends as bloat.+The read rate is the FIRST readout, before any score: `read_cookbook` was called by 0 of 16+zone sessions on `scenes_v1_flash` although the prompt named five chapters by title, and+shipping a nicer file format without measuring reads would repeat that at a new price.++---++## 5. What the tests guarantee++`tests/skills/` — 590 offline tests, plus 4 live and 3 slow.++| file | guarantees |+|---|---|+| `test_loader.py` | the spec's field rules, as the loader enforces them |+| `test_spec_compliance.py` | the same rules re-derived from the raw bytes, **plus the reference validator** (`pip install skills-ref` → the `agentskills` CLI) and a field-by-field agreement check between its `read-properties` and our loader |+| `test_library.py` | body budget, no 20-line code fences, no restating `conventions.py`, every `_claims` number still matches its live constant, **no two skills point one claim key at different numbers** |+| `test_freshness.py` | every tool, gate kind, rubric criterion, constant, switch, sibling skill and cookbook section a bundle names still exists |+| `test_router.py` / `test_routing_property.py` | the four routing laws, by row and over the whole input space |+| `test_budget.py` | the index cost, re-measured against the shipped descriptions |+| `test_corpus.py` | evidence labels and corpus claims recomputed from `bench/out` |+| `test_telemetry.py` | the read probe, including the false-positive split |+| `test_packaging.py` | **a built wheel contains all 14 `SKILL.md`, all 14 `references/`, all 9 `_claims`** |+| `test_live_discovery.py` | §7 — a real CLI actually finds and opens a bundle |++Two contradiction checks are worth separating, because they answer different questions:++* **value-level**, library-wide: two skills may not point one claim key at different+ numbers. Compared on the *pre-scale value*, not the rendered text — `cv3d-bbox-contract`+ says "1 cm" and `cv3d-repeats-and-mirrors` says "0.01" metres, and both are right.+ Failing that pair would teach the next author to delete the claim.+* **text-level**, co-routing only: two skills that can land in one session and chose the+ same units must read the same.++### What these tests caught++* **Three `contract.md` files told the agent to interpenetrate.** `blender` said "2–4 mm+ overlap is fine", `cadquery` "overlap (≥ 2 mm) … is required", and `threejs`'s worked+ example drove a leg 4 mm into a seat — while `connectivity.py` WARNs above+ `PENETRATION_WARN_M = 2 mm` and its own `fix_hint` says "overlap by ≤ 2 mm". Fixed, and+ the check is now standing.+* **Four bundles' `verified:` dates were YAML dates, not strings** — the spec says metadata+ is string→string. Quoted; `validate_bundle` now reports it instead of coercing.+* **`cv3d-opengl-pipeline` claimed `measured` on n=5.** Now `mixed`.+* **The api-agent index cost 780 tokens for five skills** against a 300-token budget,+ because it quoted whole 1024-char descriptions. It quotes the first clause now (342+ tokens for the worst real session, 400 is the ceiling): our router already decided, so+ that index is a pointer, not a matcher.+* **The live smoke had never run.** It skipped every CLI because it looked for a binary+ named after the agent kind — `gemini-cli` runs `gemini`, `claude-code` runs `claude`.++---++## 6. Does it help? The A/B++<!-- AB-RESULT -->++---++## 7. Native loading — proven, not argued++`pytest -m live tests/skills/test_live_discovery.py`. A probe bundle is materialised into a+scratch workspace, the CLI is given a task matching its description, and the assertion is+the read probe itself plus a magic word that only lives in `references/`.++| CLI | version | discovery root | surfaced | deep | followed |+|---|---|---|---|---|---|+| gemini-cli | 0.53.0 | `.agents/skills/` | yes | yes | yes |+| codex | 0.149.0 | `.agents/skills/` | yes | yes | yes |+| claude-code | 2.1.245 | `.claude/skills/` | yes | yes | yes |+| agy (antigravity) | 1.1.20 | `.agents/skills/` | yes | yes | yes |++All four discover the library natively, with no injection from us. Two things this settled+that had only been argued statically:++* `Skill` was **absent** from `ALLOWED_TOOLS` in `agents/claude_code.py`, so claude-code+ would have denied its own skill tool. Added; `3dcv doctor --skills` now checks it.+* gemini-cli's `activate_skill` consent prompt does not block us under+ `--approval-mode yolo`. This was the one claim that could not be verified statically.++**The surfaced-vs-deep split holds.** Controlled check: a bundle whose description does+*not* match the task, with the prompt "do not read any files, do not activate any skill" —+codex opened `SKILL.md` (its discovery scan reads the frontmatter) and left+`references/zebra.md` at `atime == mtime`. That is exactly the design: tier-1 scan bumps+SKILL.md, only a real read bumps `references/`.++---++## 8. How to add a skill++1. `codeverse/skills/<name>/SKILL.md` — `name` equals the directory name, lowercase+ `a-z0-9` and single hyphens; `description` (≤ 1024 chars) says WHAT and WHEN, because it+ is the only text a CLI matches on; **no `<` or `>` anywhere in the frontmatter** (the+ spec's prompt-injection rule); only spec keys at the top level, everything of ours under+ `metadata`; `metadata.evidence` and `metadata.verified` (a *quoted* ISO date) required.+2. `codeverse/skills/<name>/references/*.md` — **required**, one level. Without it the+ bundle can never score on the read metric.+3. `codeverse/skills/_claims/<name>.toml` — one row per number the body quotes from live+ code, so moving the constant breaks the test that ships the sentence:++ ```toml+ [[claim]]+ key = "penetration_error_m"+ text = "10 mm" # must appear in the body+ python = "codeverse.spatial.connectivity:PENETRATION_ERROR_M"+ scale = 1000+ format = "{:.0f} mm"+ ```+4. Add its rows to `ROUTES` in `codeverse/skills/registry.py`, in the same commit.+5. `3dcv skills validate --strict` and `pytest tests/skills`.++Body rules: ≤ 350 lines and ≤ 2,500 tokens; no code fence over 20 lines; never restate a+frame, unit or naming rule (`conventions.py` owns those); every corpus percentage carries+its battery, its n and its date.++---++## 9. Known open++* **Corpus percentages are checked for provenance, not recomputed.** A body's "47 graded+ blender runs" is a *slice* (one battery, one track, one round kind) and `bench/out` holds+ 139 blender runs overall; without each claim declaring the query that produced it, a+ tight recomputation compares two different populations. The fix is to declare corpus+ queries the way `_claims/*.toml` declares constants. What is enforced today: a claim may+ not exceed what `bench/out` holds, `measured` needs n ≥ 20, and every rate names its+ battery / n / date.+* **The wider prompt corpus still contradicts the connectivity gate on weld overlap.**+ `contract.md` was fixed for all three languages, but `tracks/generate_static.j2`+ ("overlap neighbours by ≥ 0.002 m (push a leg 2-5 mm into the seat)"),+ `tracks/assemble_static.j2`, `generate_static_part.j2`, `system/harness_contract.md`+ ("seams overlap by ≥ 2 mm") and three cookbooks still teach 2–5 mm, which is at or above+ `PENETRATION_WARN_M`. That is a prompt-corpus change with its own measurement, not a+ skills change, and it is the single most likely reason a contact skill would fail to move+ the number it targets. **Do this before re-running the A/B.**+* **`ENV_RECIPES` / `ZONE_RECIPES` inlining in `tracks/scene.py` is untouched.** It is the+ control arm for the scene track's version of this question — up to 6,000 unconditional+ tokens per env/zone session — and has not been A/B'd against a routed skill.+* **api-agent read calibration is unmeasured.** Signal 3 (exact reads) exists and is unit+ tested, but no real battery has yet produced a session where it can be compared against+ the atime probe's answer.+* **`cadquery` and `threejs` bundles are routed off.** They stay off until each language+ reaches 20 graded runs.