Skip to content

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.md
index 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-24
Sign-off for the first release intended to be called **stable**. Five parallel waves hunted
the 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 hunted
Six 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 fixed
Every fix below landed with a regression test that was **proved to fail without it** — the
source change stashed, the test run, the change restored. The 24 tests belonging to the wave
that 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, a
CP-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; both
landed 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 changes
Things 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 at
all, 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 sco
preflight that runs one trivial turn per CLI arm and classifies a backend model rejection as
a 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 5
Two defects here, both fixed, both affecting **recorded cost and model attribution** rather
than 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 model
the 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 ot
row). 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 correct
The `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 incre
cancelled") are right, and no 1 September repricing is pending. Opus 5 confirmed at $5 / $25
and 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 reviewers
Three 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 CI
runner has (PORT-2).
-### Smoke matrix
+#### Smoke matrix
55 cells. **47 ok, 0 failed, 8 skipped.** All four cells that failed on the hunt were
re-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 probe
Sign-off re-runs of rows 15, 19, 26 and 52 used four subscription-CLI or offline calls and
did 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 was
running, and `git -C /home/yipeng/3dcodeverse status --short` is empty at this commit.
diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.md
index 7b3fec47..37b7f245 100644
--- a/harness/docs/SKILLS.md
+++ b/harness/docs/SKILLS.md
@@ -1,98 +1,271 @@
-# Skills — the authoring contract
+# Skills
A **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.