Publish current portable PACTBench release

Mirror the reviewed PACTBench release: current documentation, code, published checkpoints, row-level artifacts, and registry. Validated with 47 unit tests and the 7,382-check artifact gate.

.gitattributes

@@ -37,3 +37,11 @@ results/hk/beliefs_l1_main_official_test.jsonl filter=lfs diff=lfs merge=lfs -te
 results/vrising/beliefs_l1_main_official_test.jsonl filter=lfs diff=lfs merge=lfs -text
 results/hk/beliefs_l1_main_official_test_v2.jsonl filter=lfs diff=lfs merge=lfs -text
 组会6_三游戏汇总.pptx filter=lfs diff=lfs merge=lfs -text
+pact/__pycache__/train_rgb_situation_net.cpython-313.pyc filter=lfs diff=lfs merge=lfs -text
+pact/__pycache__/validate_pactbench.cpython-313.pyc filter=lfs diff=lfs merge=lfs -text
+results/hk/beliefs_l1_main_official_test_compact_side_v1.jsonl filter=lfs diff=lfs merge=lfs -text
+results/hk/beliefs_l1_main_train.jsonl filter=lfs diff=lfs merge=lfs -text
+results/hk/eval_runs/L1-IMG-ABLATION/beliefs_rgb_shuffled_within_boss.jsonl filter=lfs diff=lfs merge=lfs -text
+results/hk/experiments/beliefs_l1_matched_foundation10k_seed0_official_test10.jsonl filter=lfs diff=lfs merge=lfs -text
+results/isaac/beliefs_l1_main_train.jsonl filter=lfs diff=lfs merge=lfs -text
+results/vrising/eval_runs/L1-IMG-ABLATION/beliefs_rgb_shuffled_within_boss.jsonl filter=lfs diff=lfs merge=lfs -text

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to PACTBench
+
+## Development setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+```
+
+Before submitting a change, run:
+
+```bash
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
+python3 pact/validate_pactbench.py --require_v5
+```
+
+Shell entry points must also pass `bash -n`.
+
+## Code and experiment changes
+
+- Put shared Python implementation in `pact/`.
+- Keep per-game files in `games/<game>/` as thin wrappers and configuration.
+- Do not hand-edit published aggregate values in `registry/registry.json`.
+- A result is publishable only when its code, configuration, ordered rows,
+  metrics, model identity, and source identities are available to the gate.
+- Keep unreviewed runs outside the published registry and README results. Follow
+  the review-isolation procedure in `docs/MAINTAINERS.md`.
+
+## Repository hygiene
+
+Do not commit:
+
+- API keys, access tokens, private endpoints, or credential files;
+- machine-specific absolute paths in code or documentation;
+- raw caches that can be rebuilt from documented inputs;
+- internal reviews, meeting notes, temporary reports, or backup copies;
+- new headline numbers that have not passed maintainer review.
+
+Use environment variables for model paths, service URLs, and credentials.
+Keep one canonical implementation for every runnable tool; avoid copied scripts
+that can silently diverge.
+
+## Documentation
+
+Update the narrowest relevant document. Dataset facts belong in `docs/DATA.md`,
+experiment definitions and results in `docs/EXPERIMENTS.md`, commands in
+`docs/REPRODUCE.md`, and game-specific entry points in the corresponding game
+README. Historical reasoning and future experiment wish lists do not belong in
+the release documentation.

README.md

@@ -1,161 +1,110 @@
-# PACTBench — 三游戏分层实验目录
+# PACTBench
 
-这是 PACT 实验的**唯一工作目录**。数据怎么造的、做了哪些实验、每个实验对应哪个 ckpt 和哪段代码，
-全在这里，且**每条路径都被 `registry/build_registry.py` 逐条核验存在于磁盘**。新实验直接在这里做，不要另起炉灶。
+PACTBench evaluates a layered boss-control system across **V Rising**,
+**Hollow Knight**, and **The Binding of Isaac**:
 
-三个游戏（V Rising / Hollow Knight / Isaac）**共用同一套流程、同一套 `obs` schema、同一套核心实验块**。
-每个游戏的完整说明在各自的 README：
+- **L1** converts causal RGB history into a compact, decision-facing belief.
+- **L2** selects among anonymous skill options from the belief and the visible
+  skill-mechanics descriptions.
 
-| 游戏 | boss | 官方测试行数 | 说明 |
-|---|---:|---:|---|
-| [V Rising](games/vrising/README.md) | 3 | 8,075 | 主战场，消融最全（另有 3 项独有实验，见下）|
-| [Hollow Knight](games/hk/README.md) | 3 | 8,360 | 核心块齐 + 历史帧消融（独有）|
-| [Isaac](games/isaac/README.md) | 8 | 1,784 | 核心块齐，几何最难（像素量纲，见坑 ①）|
+This directory is the release unit for code, checkpoints, published metrics,
+and reproducibility metadata. Machine-readable publication state lives in
+[`registry/registry.json`](registry/registry.json); prose never overrides the
+registry or the referenced metric files.
 
-## 完整实验清单（权威来源）
+## Current release
 
-**`python3 registry/status.py` 是实验清单的唯一权威**——逐块显示三个游戏各自做没做、以及哪些是某游戏独有。
-下面是当前快照（2026-07-14），迁移后请以 `status.py` 实时输出为准：
+The published snapshot uses fight-disjoint splits, the compact belief
+interface, balanced-v3 L2 sampling, HP-free-v6 prompts, anonymous option IDs,
+Gemma-4-E2B-it at temperature zero, and deterministic sample seed 0.
 
-| 实验块 | 目的 | V Rising | HK | Isaac |
-|---|---|:-:|:-:|:-:|
-| 数据审计与切分 | fight 级切分、零帧泄漏 | ✅ | ✅ | ✅ |
-| L1 主对比（视觉基线）| 优于冻结 DINOv2/VideoMAE probe | ✅ | ✅ | ✅ |
-| L1 预测可信度（无图先验）| 几何靠看图，非背训练分布 | ✅ | ✅ | ✅ |
-| L1 官方评测（主表）| L1 几何精度 / belief 接口可信 | ✅ | ✅ | ✅ |
-| L1 筛选字段（belief probe）| 紧凑 belief 够用、tracker 状态是关键 | ✅ | ✅ | ✅ |
-| L1 消融 img | 同"无图先验"配套的字段级分解 | ✅ | ✅ | ✅ |
-| L2 机制语义（compact+full）| L2 读机制推理而非背名字 | ✅ | ✅ | ✅ |
-| L2 图像模态消融 | 加当前帧不改变决策 | ✅ | ✅ | ✅ |
-| **L2 理由-决策对应（核心）** | 理由是否支持自己的决策（确定性审计+3负对照） | ✅ | ✅ | ✅ |
-| **L1 历史帧消融** | 几何主要由当前帧承载 | — | ✅（独有）| — |
-| **L2 模型消融（换 LLM）** | 可控性不随 LLM 变大而变好 | ✅（独有）| — | — |
-| **L1 延迟基准（batch=8）** | L1 快到能进闭环 | ✅（独有）| — | — |
-| CLIP 理由余弦诊断 | 负结果，已弃用（仅 V Rising 试过）| ✅（负）| — | — |
-| L2 决策质量（LLM judge）| 决策"好不好"（非"是否被语义控制"）| ⏸ | ⏸ | ⏸ |
+### L1 official evaluation
 
-三游戏的**核心 8 块完全对齐**；独有项（历史帧 / 模型消融 / 延迟 / CLIP）与暂缓项（LLM judge，口径未定）如上标注，不隐藏缺口。
+| Game | Test rows | Distance MAE | Angle MAE | Distance-bin accuracy | Angle-bin accuracy |
+|---|---:|---:|---:|---:|---:|
+| V Rising | 8,075 | 0.2620 | 11.7599° | 0.8320 | 0.7201 |
+| Hollow Knight | 8,360 | 0.4680 | 3.6527° | 0.7261 | 0.9646 |
+| Isaac | 1,784 | 9.0263 px | 29.6388° | 0.9036 | 0.8352 |
 
----
+Isaac distance is measured in pixels and is not directly comparable to the
+engine-unit distance used by the other two games.
 
-## 目录结构
+### L2 natural-ready semantic intervention
 
-```
-pactbench/
-├── env.sh                  # source 它：设 BENCH 根 + gemma endpoint
-├── games/{vrising,hk,isaac}/
-│   ├── README.md           # ★ 该游戏：数据构造 / 实验 / ckpt / 代码 / 数字
-│   ├── config.json         # 游戏配置（切分策略、L1 输入、L2 协议）
-│   ├── ontology.json       # 动作/技能 ontology（从 render_view prompt 推出来的）
-│   ├── skill_library.json  # 技能库：机制描述 + 冷却 + 时长（L2 的输入）
-│   ├── manifest.json       # fight 级切分 manifest
-│   └── {data,l1,l2}/*.sh   # ★ 跑实验的入口（薄壳）
-├── pipelines/              # 正典 shell：薄壳最终调用的东西
-│   ├── l1/{train,eval,baselines}/
-│   └── l2/{run_semantic_views_*.sh, run_image_modality_ablation.sh, llm_judge/}
-├── pact/                   # 共享 python ���现（三个游戏同一份代码）
-│   └── deprecated/         # 废弃脚本，附说明，不要引用
-├── ckpt/{vrising,hk,isaac}/   # ★ 训好的 ckpt（真文件）
-├── results/{vrising,hk,isaac}/ # ★ 所有实验产物：metrics / beliefs / eval_runs / ablations
-├── registry/               # registry.json（机器可读索引）+ build_registry.py + status.py
-├── schemas/                # 跨游戏 schema（belief schema、director profiles）
-├── data -> ../data         # 软链：原始+processed 数据（105G，不占本目录）
-└── out  -> ../out          # 软链：RGB cache（60G，可分钟级重建）
-```
+| Game | Valid paired states | Mean menu size | Menu-aware chance | Description-follow |
+|---|---:|---:|---:|---:|
+| V Rising | 200 | 4.875 | 21.93% | 67.0% |
+| Hollow Knight | 200 | 5.370 | 18.78% | 79.5% |
+| Isaac | 122 | 2.238 | 46.04% | 83.6% |
 
-**为什么 data/ 和 out/ 是软链**：它们是 165G 的大文件，且 `out/` 里全是可重建的 RGB cache。
-真正的资产（代码、ckpt、指标、beliefs）都是本目录里的真文件，加起来不到 400 MB。
+The 200 source states are fixed before L2 outputs are read. Isaac has 122
+valid semantic-swap pairs because the predefined intervention requires at
+least two tracker-ready options; singleton menus are excluded before outcome
+aggregation. The fixed two-choice controls are reported separately in
+[`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md).
 
-## 现在是什么状态
-
-```bash
-python3 registry/status.py          # 逐项状态表（哪个游戏的哪个实验块做完了）
-python3 registry/build_registry.py  # 重新核验并生成 registry.json（改了实验就跑一次）
-```
+The L1 visual comparison is a comparison of complete training schemes:
+PACT-L1 is task-trained end to end, whereas DINOv2-S and VideoMAE-B are frozen
+pretrained backbones with trained probes. It is not an isolated backbone claim.
 
-`registry/build_registry.py` 会**核验每条路径真的存在、每个数字真的从它声称的 metrics 文件里读出来**；
-查无此文件就报错退出。所以这个索引不可能和实际跑过的东西脱节。
+V Rising also includes a separate accepted L1 comparison experiment that trains
+DINOv2-S end to end on the same ordered 18,068/8,075 rows and the matched PACT
+two-stage recipe. In this configuration it remains less accurate and 48.79%
+slower at batch 1 than PACT-L1; the evidence and claim scope are recorded in
+[`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md#v-rising-end-to-end-dinov2-s-l1-comparison-experiment).
 
-## 怎么跑
+## Quick start
 
 ```bash
-source env.sh                                   # 工作目录 = BENCH 根
-
-# 数据（三个游戏同构）
-bash games/{game}/data/audit_dataset.sh         # 审计 + 切分核验
-python3 games/{game}/data/build_metadata.py     # ontology + 技能库（vrising 除外，见其 README）
-bash games/{game}/data/build_manifest.sh        # fight 级切分 manifest
-
-# L1
-CUDA_VISIBLE_DEVICES=<gpu> bash games/{game}/l1/train_l1.sh
-bash games/{game}/l1/eval_official_from_ckpt.sh # 从 ckpt 评测（不训练，可共享 GPU）
-
-# L2（先起 gemma server）
-/dev_vepfs/junhaochen/envs/gemma4-venv/bin/python pact/gemma_server.py &
-bash games/{game}/l2/run_semantic_views.sh
+cd pactbench
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install -r requirements.txt
+
+python3 registry/status.py
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
+python3 pact/validate_pactbench.py --require_v5
 ```
 
-RGB cache **必须并行建**：`python3 pact/build_rgb_frame_cache.py --workers 32`。
-串行建一个 8,360 样本的 cache 要约 2.5 小时，并行 138 秒（结果逐字节一致，已验证）。
+The full artifact gate should end with:
 
----
-
-## 数据是怎么构造的（三游戏共用）
-
-```
-data/{game}/processed/{Boss}/
-    dataset_manifest.json
-    policy_view_fight{N}.jsonl     ← 决策行：action + obs（dp / da / rel_angle / time_since / boss_hp_frac …）
-    render_view_fight{N}.jsonl     ← 渲染 prompt（技能机制描述的来源）
-    video_fight{N}.mp4             ← 对应视频
+```text
+PACTBench gate: PASS (7382 checks)
 ```
 
-**切分是 fight 级的**：每个 boss 按 fight 排序，最后 N 场作 test、前 M 场作 val、其余作 train。
-切分单位是整场对局，所以训练/测试之间不存在同一场内的帧泄漏（三个游戏都逐行核验过，零越界样本）。
+Large raw data and RGB caches are exposed through `data -> ../data` and
+`out -> ../out`. See the reproducibility guide before rebuilding or moving
+them.
 
-**技能机制描述不是人手编的**：来自 `render_view` 里的 prompt 短语（"boss_1 performs …"）；
-冷却/时长统计直接来自 `policy_view` 的日志行。`build_game_metadata.py` 里只有 `MECHANICS` 表是每游戏特有的。
+## Documentation
 
-## L2 统一协议
+| Document | Purpose |
+|---|---|
+| [`docs/DATA.md`](docs/DATA.md) | Data source, layout, schema, split, and audit rules |
+| [`docs/EXPERIMENTS.md`](docs/EXPERIMENTS.md) | Exact protocols, published results, and claim scope |
+| [`docs/REPRODUCE.md`](docs/REPRODUCE.md) | Environment, commands, expected artifacts, and release gate |
+| [`docs/MAINTAINERS.md`](docs/MAINTAINERS.md) | Handoff, review isolation, registry update, and release procedure |
+| [`games/vrising/README.md`](games/vrising/README.md) | V Rising entry points and artifacts |
+| [`games/hk/README.md`](games/hk/README.md) | Hollow Knight entry points and artifacts |
+| [`games/isaac/README.md`](games/isaac/README.md) | Isaac entry points and artifacts |
+| [`pipelines/l2/llm_judge/README.md`](pipelines/l2/llm_judge/README.md) | External decision-quality judge protocol |
 
-**compact 视图 + gemma-4-E2B-it + 温度 0 + 200 个分层状态 + 匿名技能 ID**，三种 prompt：完整 / 抹除描述 / 交换描述。
-匿名技能 ID 是关键——它让模型没法靠技能名字猜，只能读机制描述做推理。
-每个 L2 run 目录里都有三件套：`metrics.json` / `rows.jsonl` / `run_config.json`（溯源）。
+## Repository layout
 
----
-
-## 两个必须知道的坑
-
-**① 距离量纲每个游戏不一样。** `obs.dp` 在 V Rising / HK 是引擎单位（0–15），在 Isaac 是**像素**（24–484，中位数 147）。
-训练脚本原先把归一化常数写死为 30、预测 clamp 在 `1.5 × 30 = 45` —— **任何 dp > 45 的游戏，预测都会被静默压平在 45**
-（Isaac 实测预测中位数 45.0，真值 146.5）。现已提为 CLI 参数，默认值不变（V Rising / HK 零影响）：
-
-```bash
---distance_norm 1000.0 --distance_clamp 1.5     # Isaac 必须这样
+```text
+pactbench/
+├── games/{vrising,hk,isaac}/  # per-game configuration and thin entry points
+├── pipelines/                 # shared shell pipelines
+├── pact/                      # shared Python implementation
+├── ckpt/                      # published L1 checkpoints
+├── results/                   # published row-level and aggregate artifacts
+├── registry/                  # machine-readable publication snapshot
+├── schemas/                   # cross-game schemas
+├── tests/                     # regression and provenance tests
+├── data -> ../data            # large source/processed data
+└── out  -> ../out             # rebuildable caches
 ```
 
-**接入第四个游戏时，先看它的 `obs.dp` 分布再定 `distance_norm`。**
-
-**② L2 的分层采样曾经是坏的（v1）。** `choose_rows` 原先只按 `(boss, dp_bin)` 分桶，而行是按 fight 排序的，
-于是 200 个状态**全部塌缩到每个 boss 的第一场**，数字被高估。现已改为按 `(boss, fight, dp_bin)` 分层，
-`sample_set_id` = **`L2-SAMPLE-200-v2`**。**只引用 v2 的结果。**
-
-## 已知缺口
-
-- **HK 的 `player_angle_bin` 分类头 acc = 0.0000**（连续角度 3.65° 正常）。是这个 bin 头本身坏了，**未修**。
-  不影响 L2（compact 视图不含该字段）。同一个头在 V Rising 是 0.72、Isaac 是 0.79。
-- **V Rising 的 RGB cache 已被磁盘写满时清除**。ckpt / beliefs / metrics 都在，**L2 仍可复现**；
-  重跑 L1 评测需先从 `data/processed`（38G，完好）重建 cache。
-- **L2 决策质量的评价口径未定**（LLM judge 在另一台机器上跑），三个游戏都是 `暂缓`。
-
-## 不在这个目录里的东西
-
-V Rising 的 **L3/L4 闭环与世界模型**（GameMasterDiT 渲染、skill recognizer、closed-loop rollout）
-留在旧的 `../` 目录，7-02 后没再动过。它是另一条线，本目录只管三游戏的 L1（理解）与 L2（决策）。
-迁移细节与旧路径映射见 [docs/MIGRATION.md](docs/MIGRATION.md)。
-
-## 检查记录（转交必读）
-
-本仓库经过多轮独立复算与对抗式排查：**检查了什么、排除了哪些错误、还剩哪些必须诚实披露的口径**，
-全部写在 [docs/CHECK_RECORD.md](docs/CHECK_RECORD.md)（技术细节见 [docs/AUDIT_20260714.md](docs/AUDIT_20260714.md)）。
-接手前请先读它——尤其是**基线口径**（"专训小网 vs 冻结基础特征"，非"架构 vs DINOv2"）与各实验的残留边界。
+The decision-quality LLM judge is intentionally run on a separate machine.
+Its absence from the local deterministic gate does not change the publication
+status of the local L1 and L2 intervention artifacts.

ckpt/hk/{l1_main_train30k_e10.pt → l1_main_train30k_e10_provenance_v2.pt}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:7d3bb58d56c4a9f6cd9d46b3c02dfcd70b36cd55d93be499ec468910f3c21d99
-size 52294395
+oid sha256:94f794ec6f9a59b43ae95c848498eda38bb609f999a867214425d74bbb604019
+size 52290187

ckpt/hk/l1_main_train30k_e10_provenance_v2.pt.sha256.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "size": 52290187,
+    "mtime_ns": 1784222948115395649
+  },
+  "sha256": "94f794ec6f9a59b43ae95c848498eda38bb609f999a867214425d74bbb604019"
+}

ckpt/{isaac/l1_DEPRECATED_broken_default_norm_e10.pt → hk/l1_matched_foundation10k_seed0_e10.pt}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:2b67e739ce66e4d989a4b41fd51ab984526cacf5fccb1572a47efd87f3b37b5a
-size 52292027
+oid sha256:9175df322abc57d765546858d008893d7dbb92fd47a181e41e410e9946575a86
+size 52285499

ckpt/hk/l1_matched_foundation10k_seed0_e10.pt.sha256.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "size": 52285499,
+    "mtime_ns": 1784352040876326577
+  },
+  "sha256": "9175df322abc57d765546858d008893d7dbb92fd47a181e41e410e9946575a86"
+}

ckpt/isaac/{l1_main_fixed_e10.pt → l1_full_gradientfix_seed0_e10.pt}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:775a53dd91d5c73a659956e5988a9588f29b882cc74d1d903e531bf37db9f5e0
-size 52284307
+oid sha256:8b09473f7b4a2d846fa03a352a9b17f2d5c43a872369dbb9f2db808c5148be4b
+size 52283195

ckpt/isaac/{l1_variant_norm_e10.pt → l1_full_gradientfix_validation_selected_seed0_e10.pt}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:5a62e6aa5cda1e68dbb2923e1c5569fe7cff433ee213d418dc22780aab419dcb
-size 52284043
+oid sha256:fd25533342963395bd8a251cc84a4a6ca2ae7e26201d2cab307c7f53ed4797de
+size 52283259

ckpt/isaac/l1_full_gradientfix_validation_selected_seed0_e10.pt.sha256.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "size": 52283259,
+    "mtime_ns": 1784358217777012145
+  },
+  "sha256": "fd25533342963395bd8a251cc84a4a6ca2ae7e26201d2cab307c7f53ed4797de"
+}

ckpt/isaac/l1_main_distance_scale_v2_e10.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3318896744914b5b5dbc91063ccfc61412d6eb7e6b322e4092b1c757f1473b1d
+size 52283067

ckpt/isaac/l1_main_distance_scale_v2_e10.pt.sha256.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "size": 52283067,
+    "mtime_ns": 1784233413358911636
+  },
+  "sha256": "3318896744914b5b5dbc91063ccfc61412d6eb7e6b322e4092b1c757f1473b1d"
+}

ckpt/{vrising/l1_main_resnet18_e10.pt → isaac/l1_matched_foundation9484_validation_selected_seed0_e10.pt}

@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:ccd32dd52d7bbfaaa858ebc4de5a869468310210bed920f7b4ce8ef5945066f6
+oid sha256:df7530cf7d80df87fca873fedd7ce6dd38a9a4e27e5bf6a37d21e87f300ab368
 size 52283323

ckpt/isaac/weight_sweep/l1_distance_w16_validation_seed0.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:80a343234e8e1e7d4417c8907e915af65d1dd8d3d526dedf31f32507aea66b75
+size 52283323

ckpt/isaac/weight_sweep/l1_distance_w2_validation_seed0.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:403c0bd5f7110425e2748b52dbc2edf2c5b4384c5aa905fc92cf7c101a5d1cdb
+size 52283323

ckpt/isaac/weight_sweep/l1_distance_w4_validation_seed0.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7235293af5c5693c4b6690d39fbe81920ff69720e6e4482ff1dfbd63cc157325
+size 52283323

ckpt/isaac/weight_sweep/l1_distance_w8_validation_seed0.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e0e2dc0376c01c382da0ed280bf10ba198b5dbaba86a9cb1329ed9d56d589934
+size 52283323

ckpt/vrising/l1_dinov2_small_end_to_end_matched20.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5fc5c18c585fdb19da1c3c680754616d1ef782d293434e9e61e2358d6b2f71cb
+size 93876943

ckpt/vrising/l1_dinov2_small_geom_stage1_e10.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ac2cb75bcb735e0cfb788789876bb0794506ad02de3286184c550bc9705d24a6
+size 93875663

ckpt/vrising/l1_main_resnet18_e10_provenance_v2.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:904f0106e258391084573ccd8f6c8c607d4353607697e07ec2826f82bd579d00
+size 52279115

ckpt/vrising/l1_main_resnet18_e10_provenance_v2.pt.sha256.json

@@ -0,0 +1,7 @@
+{
+  "identity": {
+    "size": 52279115,
+    "mtime_ns": 1784222849344310076
+  },
+  "sha256": "904f0106e258391084573ccd8f6c8c607d4353607697e07ec2826f82bd579d00"
+}

docs/AUDIT_20260714.md

@@ -1,72 +0,0 @@
-# 全面审计报告(2026-07-14)
-
-背景:L2 输入污染、基线单 boss 训练、manifest 被覆盖等连环问题暴露后,对**全部实验**按错误模式做结构化排查。
-方法:按 7 类错误模式逐类扫描,每项给出证据;修复分「已修」「重跑中」「收口待办」。
-
-## 一、实锤问题(全部已定位根因)
-
-| # | 问题 | 根因 | 状态 |
-|---|---|---|---|
-| P1 | HK/Isaac L2 输入 prev/hp 96-98% 错、大量跨boss | write_beliefs 无差别覆盖:未训练头(不在 loss_fields)输出顶掉 tracker 真值;一个键两种语义 | ✅已修(命名空间隔离+field_source)+v2过五闸门100%+**L2矩阵重跑中(v3)** |
-| P2 | 基线(DINOv2/VideoMAE)训练只见 1 个 boss | train_rows[:10000] 全局掐头+行按boss排序;HK=100%FalseKnight,Isaac=100%Dingle;评测集 75-81% 是未见boss → 对比不公平,PACT优势被夸大 | ✅已修(balanced_limit,与PACT同款)+**4任务公平重跑中** |
-| P3 | HK 官方 test10 manifest 被覆盖成 test3 | build_manifest.sh 写死 --test_count 3;**我 07-13 验证重跑时覆盖**(mtime 13:44);波及HK基线评测(2242)与HK probe | ✅manifest已恢复test10并逐项核对;shell默认改10 |
-| P4 | threshold KeyError 被兜底补丁盖掉 | 那个 KeyError 正是 P2「训练集缺boss」的直接症状,当时只修症状未追根因 | ⚠流程教训,已入闸门纪律 |
-| P5 | HK angle_bin 头 acc=0(训过但坏) | **根因今日锁定**:train 30k 里 center 类只有 1 个样本(HK横版几何few center)+逆频类权重→头塌缩恒预测center,eval 无center→0 | 已文档化;修复可选(重分桶/去权重),角度证据用连续头(3.65°) |
-| P6 | 我的核查器误报 V Rising 污染 | 检查器拿匿名ID对原始名 | ✅已纠;检查器负对照纪律建立 |
-| P7 | 历史:L2采样v1塌缩/量纲30/坏ckpt默认等 | 见 VERIFICATION.md | ✅早已修复 |
-
-## 二、排查后确认干净(逐项验证,非推断)
-
-- **原始belief真值**:cache 全量 HK 8360+Isaac 1784,prev/hp 100% 真值、跨boss 0
-- **几何血缘**:distance_bin 三游戏均 value 派生(训练过的回归)→ L1 几何表合法;PPT p4 未报未训练头
-- **PACT-30k 均衡**:HK 14k/10k/11.6k 三boss、Isaac 八boss全有(cache builder 用 balanced_limit)
-- **skill_library 覆盖风险解除**:再生成逐字节一致(确定性函数);rationale 词法旁证 desc-follow≈100%
-- **V Rising L2 全线干净**:prev 200/200(经去匿名化核查);hp=high 为文档声明的已知局限
-- **污染v1 beliefs 消费者清查**:除已知 L2(重跑中)外无隐藏消费者;probe/无图/延迟/几何表不受污染
-- **截断扫描**:其余 [:limit] 均未激活(canonical 未用 limit)或本就是 fight 切分语义;probe eval limit 已卫生修复为 balanced
-- **cooldown 语义**:全默认行仅 0.4%/4.5%(开局行),非污染
-- **考卷盘点**:官方口径 8360/1784/8075;legacy test3=2242 仅用于 HK 历史帧消融(两臂同口径,内部一致)与 HK probe(将对齐重跑)
-
-## 三、新增的结构性防线
-
-1. **validate_beliefs.py 五闸门接入 L2 shell**:不过闸门拒跑(exit 3);负对照(污染文件必须FAIL)+正对照(VRising必须PASS)双向验证过
-2. **一键一语义**:预测进 head_predictions 命名空间,field_source 记血缘,未训练头出口被结构性封死
-3. **balanced_limit 统一**:基线与 PACT 同采样函数
-4. **run_config 记录 skill_library/beliefs 的 sha256**(不再只存路径)
-5. **入口幂等**:build_manifest 默认与正典一致;train shell 默认 BELIEF_OUT 指 v2
-
-## 四、进行中/收口待办
-
-- L2 矩阵 v3:HK compact 200/200✓ full 169/200;Isaac compact 200/200✓ full 187/200;之后 img×2@60
-- 公平基线:4 任务抽特征中(processed 6041/10000 processed 4264/10000 processed 4001/9484 processed 3025/9484 )
-- 跑完后:HK probe 在 test10 重跑 → 理由对应重算 → 两组 A/B 对照表(污染vs干净、不公平vs公平) → registry(v1标CONTAMINATED,v3/公平版转正) → PPT p16/17/20/22/23/28/29/30 更新+勘误 → README×3
-- 未定项:LLM judge 口径(暂缓,非缺陷)
-
-## 五、二轮排查新增(用户要求"检查所有实验步骤"时发现)
-
-| # | 问题 | 状态 |
-|---|---|---|
-| P8 | **单技能菜单上干预无定义**:正确 prev 被连招规则排出菜单后,Isaac 出现 47/200 单菜单;恒等 swap_mapping 使 follow 与 name-bias 同时恒真(v2 也有 9 行,被污染掩盖) | ✅ 已修:menu≥2 统一口径(evaluate_sample+summarize+by_boss 三层+rationale+img汇总),v2/v3 重算,自洽校验(follow≤change)全过 |
-| P9 | **by_boss 子聚合漏过滤**(主指标修了,分boss路径漏了→Monstro follow 96.7%>change 30% 自相矛盾) | ✅ 已修并复验 8 boss 全自洽 |
-| P10 | **V Rising 图像模态消融用的是 SAMPLE-v1 采样**(违反"只引用 v2";p10 数字来自塌缩采样) | 🔄 按 HK/Isaac 同款协议(v2采样@60配对)重跑中;完成后更新 p10 与 registry |
-| P11 | VR img shell 的 RUN_TAG 未定义(set -u 拦停,我早前补丁只加引用未加定义) | ✅ 已修 |
-
-**二轮补��验证(干净):** v2/v3 同一批 200 状态(A/B 有效);isaac img 子集(两视图)0 单菜单;p16/p20/p17/p21/p22/p23/p26/p28/p29/p30 全部更新为 v3/公平数字并渲染自查。
-
-## 六、三轮排查(用户"再检查别留问题"+ skill library 单/多boss 追问时发现)
-
-对抗式独立复算(4 路:L2语义/L1基线/理由+图像/PPT对账)。L2语义 6 正典运行全部指标从原始行 100% 精确复现;L1 基线 balanced_limit 全 boss 覆盖已复算确认(HK 3334/3333/3333;Isaac 7×1250+Gemini734,全 8 boss);train/test fight 三游戏零交集;PACT 主结果 eval n 与基线 n_eval 逐一吻合。新发现并修复:
-
-| # | 问题 | 影响 | 状态 |
-|---|---|---|---|
-| P12 | **理由实验入口 shell 仍指向 samplev2(污染)语义 rows**,输出也写 samplev2 目录 | registry/PPT 的 v3 理由数字是对的(产物 source_rows 指向 v3),但按文档入口复现会从污染输入重算 | ✅ 已修:shell 指向 v3 rows + v3 输出 tag;重跑到临时路径与正典逐位一致(HK recon 85.0/Isaac 58.2) |
-| P13 | **语义/图像入口 shell 默认 RUN_TAG=samplev2**(HK/Isaac 四个 shell) | 读的是干净 beliefs+强制闸门,故默认跑出的数据是干净的,但会写进 samplev2 目录→覆盖 A/B 污染存档且不重现 registry 的 v3 | ✅ 已改默认 samplev3(VR 保持 samplev2=正典) |
-| P14 | **图像 summarizer 的 within_modality 漏 menu≥2 过滤**(cross_modality 有,within 没有) | Isaac text_only follow 被 47 个单菜单行灌水到 0.835,实为 0.784 | ✅ 已修 summarizer 并重算 6 个 summary |
-| P15 | **图像消融 200-text vs 60-img 苹果比橘子**:60 img 采样状态更容易(HK 全200文本 follow 76.2% 但这 60 子集高达 93.3%),并排放会误导图像净效应 | 结论方向(图像无增益)不变,但"全线下滑"对 Isaac 不成立 | ✅ summarizer 新增 text_only_shared 公平块;PPT 改用同60口径+配对变化为主指标 |
-| P16 | 图像 SUMMARY_DIR 不含 RUN_TAG(shell 写 `_n60_seed0`,registry 指 `_samplev3_n60_seed0`) | 入口不重现 registry 目录 | ✅ 三个 image shell 的 SUMMARY_DIR 补 RUN_TAG,与 registry 对齐 |
-
-**图像消融诚实口径(重算后):** 同 60 状态 desc_follow — HK 93.3%→86.7%(降)、VR 82.4%→75.9%(降)、Isaac 60.0%→60.3%(持平);配对变化(full 描述加图改了多少决策)HK 3.3% / Isaac 12.1% / VR 10.0% → 有文本时图像基本被忽略,净效应至多中性、偶有噪声。
-
-**关于 skill library 单/多boss:** L2(gemma)始终用**每 boss 自己的技能表**构 menu(ready_menu 只从 `skill_lib[boss]` 取,无跨 boss)——不存在"单/多 boss library"开关。用户记忆中的单/多 boss 是**旧 GameMaster 像素 policy**(老 pact 目录,single-boss 头 vs joint no-boss 头),属 Decision Head 层,不在 pactbench L2 范畴。
-
-**未处理(非缺陷,已知):** Isaac 语义 rows 里 47 个单菜单行仍存 resume 前的过期行内 follow/name_bias 字段(聚合层已正确 menu≥2 剔除;分类器拒绝原地改正典 rows,风险仅限"有人绕过闸门裸重聚合",已文档告警)。

docs/BACKFILL_TODO.md

@@ -1,134 +0,0 @@
-# HK / Isaac 补做清单
-
-V Rising 做全了 8 个实验块，HK 和 Isaac 各只做了 3 个（数据 / L1 主结果 / L2 机制语义）。
-下面是要补的，**按「性价比」排序**（先做便宜且能立刻出数的）。
-
-现状（`python3 registry/status.py`）：
-
-| 实验块 | V Rising | HK | Isaac |
-|---|---|---|---|
-| 数据审计与切分 | ✅ | ✅ | ✅ |
-| L1 官方评测（主结果） | ✅ | ✅ | ✅ |
-| L2 机制语义干预 | ✅ | ✅ | ✅ |
-| **① L1 消融 img（无图先验）** | ✅ | ❌ | ❌ |
-| **② L2 模态消融（图+文 vs 纯文）** | ✅ | ❌ | ❌ |
-| **③ L1 筛选字段（belief probe）** | ✅ | ❌ | ❌ |
-| **④ L1 主对比（DINOv2 / VideoMAE 基线）** | ✅ | ❌ | ❌ |
-| ⑤ L1 消融：历史帧 | ❌ | ✅ | ❌ |
-| ⑥ L2 决策质量（LLM judge） | ⏸ | ⏸ | ⏸ |
-
----
-
-## ① L1 消融 img（无图先验）— **最便宜，先做这个**
-
-**要回答的问题**：L1 的几何预测是真的从图像里看出来的，还是靠训练集的全局先验就能猜到？
-
-- **代码**：`pact/eval_l1_no_image_no_engine_prior.py` → `pact/build_l1_img_ablation_summary.py`
-- **通用性**：✅ 纯 post-hoc，只读 `results/{game}/l1_main_official_test.json`，**已在 HK 上试跑通过**
-- **成本**：**CPU 秒级**，不需要 GPU、不需要重训
-- **要做的**：
-  1. 新建 `pipelines/l1/ablations/run_img_ablation_{hk,isaac}.sh`（照 V Rising 的 RUN_COMMANDS 抄）
-  2. `--test_set_id` 传对（HK = `TEST-OFFICIAL-8360`，Isaac = `TEST-OFFICIAL-1784`）
-  3. ⚠️ 脚本里 `train_set_id` 目前硬编码成 V Rising 的 `TRAIN-COVERED-18068`，要提成参数
-- **产出**：`results/{game}/eval_runs/*_L1-IMG-ABLATION_*/metrics.json`
-- **工作量**：**< 1 小时**
-
-## ② L2 模态消融（文本 vs 文本+图像）— 便宜，且 gemma server 已在线
-
-**要回答的问题**：给 L2 额外看一眼当前 RGB 帧，决策会更好吗？（V Rising 的结论是这层已经不缺视觉信息）
-
-- **代码**：`pact/eval_l2_skill_description_intervention.py --input_modality text_image` + `pact/summarize_l2_image_modality_ablation.py`
-- **通用性**：✅ CLI 有 `--data_root` 和 `--input_modality`，**不用改代码**
-- **成本**：200 状态 × 3 变体 = 600 次 gemma vision 调用/游戏，**约 1–2 小时/游戏**（有 `--resume`）
-- **要做的**：照 `pipelines/l2/run_image_modality_ablation.sh` 复制出 hk / isaac 版，改 4 个路径
-  （`--beliefs results/{game}/beliefs_l1_main_official_test.jsonl`、`--skill_library games/{game}/skill_library.json`、
-  `--data_root data/{game}/processed`、text_rows 指向该游戏的 canonical L2 run）
-- **工作量**：**半天**（含跑）
-
-## ③ L1 筛选字段（belief probe：compact vs overcomplete）— 需要改一处硬编码
-
-**要回答的问题**：belief schema 里哪些字段真的携带决策信息？紧凑 belief 是否优于过全 belief？
-（V Rising 的结论：oracle minimal 0.816 > full overcomplete 0.641）
-
-- **代码**：`pact/eval_l2_belief_policy.py`
-- **通用性**：⚠️ **有阻塞**。它 import `layered_belief.BOSSES`，而那是写死的 V Rising 三个 boss；
-  `--boss` 的 choices 也绑在上面。需要把 boss 列表改成**从 manifest / ontology 推**（`train_rgb_situation_net.py`
-  已经是这么做的，照抄即可）。另外 `--manifest` 默认值也是 V Rising 的。
-- **成本**：改完之后训练只是个小 MLP probe（40 epoch，~8k 行），**分钟级**
-- **工作量**：**1 天**（主要是改代码 + 核对 feature_group 定义对 HK/Isaac 是否合理）
-
-## ④ L1 主对比（DINOv2-S / VideoMAE-B 视觉基线）— 最贵，但代码是通的
-
-**要回答的问题**：PACT-L1（ResNet18+GRU，5 帧）比冻结的视觉基础模型 probe 强多少？
-
-- **代码**：`pact/eval_l1_foundation_baselines.py`（抽特征）→ `pact/retrain_l1_foundation_probe_from_cache.py`（训 probe）
-- **通用性**：✅ CLI 有 `--manifest / --processed_root / --feature_dir`，且内部走 `collect_decision_samples(manifest, ...)`
-  —— **manifest 驱动，不依赖写死的 boss 列表**。V Rising 的这条链今天刚重跑验证过 ✓
-- **成本**：**最贵的一步是抽特征**（要解码视频 + ViT 前向）：
-  HK ≈ 30k train + 8.4k test，Isaac ≈ 27k train + 1.8k test，**估计各 2–4 小时 GPU**；
-  之后 probe 训练 30 epoch 是分钟级。特征 cache 每个约 100–200 MB。
-- **要做的**：新建 `pipelines/l1/baselines/run_foundation_baselines_{hk,isaac}.sh`，传对 manifest / processed_root / feature_dir
-- **工作量**：**1–2 天**（大头是 GPU 排队）
-- ⚠️ **磁盘**：现在 `/dev_vepfs` 只剩 238G（99% 满）。特征 cache 不大，但跑之前先确认还有空间。
-
-## ⑤（可选）Isaac 的历史帧消融
-
-HK 已经做了（结论：几何主要由当前帧承载，去掉历史 MAE 只退化 6%）。Isaac 的几何最难（角度 MAE 37.6°），
-补一个能验证「这个��论是否跨游戏成立」。
-
-- **代码**：现成的 —— `bash games/isaac/l1/train_l1.sh` 传 `history_offsets=0`
-- **成本**：一次 L1 重训（GPU，约 1–2 小时）
-- **工作量**：**半天**（纯排队）
-
-## ⑥ L2 决策质量（LLM judge）— 三个游戏都卡在同一处
-
-不是 HK/Isaac 特有的缺口：**评价口径本身没定**，judge 在另一台机器上。
-`pipelines/l2/llm_judge/` 的脚本还引用 `out/layered/` 下的 legacy 中间产物。
-建议**先把口径定下来再动手**，否则三个游戏都得返工。
-
----
-
-## 建议的顺序
-
-1. **①（< 1 小时）** → 立刻让 HK/Isaac 的 L1 多一个证据块
-2. **②（半天）** → gemma server 现在就在线，趁热跑
-3. **⑤（半天，纯排队）** → 顺手补 Isaac 的历史帧
-4. **③（1 天）** → 要改 `layered_belief` 的 boss 硬编码，是这批里唯一的真代码活
-5. **④（1–2 天）** → GPU 大头，最后做
-6. **⑥** → 等口径
-
-## 顺带该修的
-
-- **HK 的 `player_angle_bin` 分类头 acc = 0.0000**（连续角度 3.65° 正常）。要在论文里报 HK 的 L1 表，
-  这个头得修或明确说明。见 `games/hk/README.md`。
-- **V Rising 的 RGB cache 没了** → L1 评测跑不了。要重跑 V Rising 的 L1（或做 ①④ 的 V Rising 对照）
-  得先 `python3 pact/build_rgb_frame_cache.py --workers 32` 重建（~30G）。
-
----
-
-## ⏸ 暂停快照（2026-07-13）
-
-**HK / Isaac 的 L2 `full` 视图跑到一半被暂停**（compact 视图三个游戏都已完成）。
-
-| | compact | full |
-|---|---|---|
-| V Rising | ✅ 85.7% | ✅ 77.4% |
-| HK | ✅ 89.8% | ⏸ **88/200 状态** |
-| Isaac | ✅ 73.0% | ⏸ **27/200 状态** |
-
-**恢复**（`rows.jsonl` 逐条 append，`--resume` 会跳过已完成的状态，不会重跑）：
-
-```bash
-source env.sh
-# 需要 gemma server 在线（127.0.0.1:8018）
-bash games/hk/l2/run_semantic_views.sh      # compact 秒过(resume) → 接着跑 full
-bash games/isaac/l2/run_semantic_views.sh
-```
-
-**关于速度（别再往并发上使劲了）**：瓶颈是 `pact/gemma_server.py` 用 batch=1 的 HF `generate`，
-一次只处理一条。实测 1 并发和 12 并发吞吐一样（~0.2 req/s），GPU 利用率只有 26%、功耗 79W/400W —— 卡在空转。
-- 已做的缓解：客户端 `--workers`（默认 6）、`GEMMA_TIMEOUT=600` + `GEMMA_RETRIES=4`（并发排队会偶发超时，
-  以前一次超时就整个 run 崩掉）。
-- 真要提速：**多起几个 server 实例把 GPU 填满**（显存充裕，80G 只用了 12G），客户端 base_url 轮询；
-  或者在 server 端做 micro-batching（收益最大，但要改 server）。
-- 单 server 实测 ~0.24 req/s，双 server ~0.47 req/s，剩余 285 个状态 ≈ 30 分钟。

docs/CHECK_RECORD.md

@@ -1,48 +0,0 @@
-# PACTBench 检查记录（转交包）
-
-> 面向 coauthor：**检查了什么、排除了哪些错误、还剩哪些口径**。
-> 权威数字见 `registry/registry.json`（`python3 registry/build_registry.py` 自校验）；技术细节见 [`AUDIT_20260714.md`](AUDIT_20260714.md)；复现见 [`REPRODUCE.md`](REPRODUCE.md)；闸门见 [`VERIFICATION.md`](VERIFICATION.md)。最后更新 2026-07-15。
-
-## 检查方法
-独立复算（从原始行重算、不信落盘 metrics，差 >0.5pt 即报）+ 对抗视角（主动找泄漏/未训练头/不公平基线/平凡解/口径不一致）+ 负对照纪律（判定器先在净/污两侧验证）+ 入口自洽（文档化 shell 默认能重现正典产物）。
-
-## 已排除的错误（均已修复并复验）
-| 错误 | 表现 | 修复 |
-|---|---|---|
-| 未训练头污染 belief | `write_beliefs` 无差别覆盖，tracker 真值被随机头覆盖（HK/Isaac prev/hp 96%+ 错、跨 boss） | 命名空间隔离 + `field_source` 血缘 + 白名单；beliefs 过五闸门 100% |
-| 基线单 boss 训练 | `train_rows[:10000]` 掐 boss 排序行 → 只训一个 boss | 改 `balanced_limit` 全 boss 覆盖；旧版存档不引用 |
-| 考卷口径错位 | HK manifest 被覆盖成 test3（8360→2242） | 恢复 test10、改 shell 默认；train/test fight 零交集 |
-| 单菜单干预无定义 | Isaac 47/200 单菜单 → swap 恒等、follow/name-bias 恒真 | 五层统一 menu≥2；follow≤change 全 boss 复验 |
-| 入口 shell 指向污染 rows | rationale/semantic/image 默认仍指 samplev2 | 改指 v3、默认 samplev3；重跑与正典逐位一致 |
-| 图像 summarizer 漏 menu≥2 | Isaac text_only follow 灌水 0.835（实 0.784） | within_modality 补 menu≥2；重算 6 summary |
-| 图像消融苹果比橘子 | 200-text vs 60-img（60 子集更易） | 加 `text_only_shared` 公平块 + 配对变化为主指标 |
-| 判定器无对照 | 匿名 ID 被误判"跨 boss" | 判定器先净/污两侧验证；VR de-anon 后 200/200 正确 |
-| 量纲静默截断 | Isaac dp 像素被 clamp 在 45 | CLI `--distance_norm 1000`；主结果 MAE 10.06 证实正确 |
-| DukeOfFlies 解释错 | 匿名跑却称"名字泄漏" | 改为"机制近义/退回槽位先验 + 测量歧义" |
-
-## 逐实验核查（全部复算通过）
-| 实验 | V Rising | HK | Isaac |
-|---|:--:|:--:|:--:|
-| 数据切分（fight 级、零交集） | ✅ | ✅ | ✅ |
-| L1 主结果 | ✅ | ✅¹ | ✅ |
-| L1 vs DINOv2/VideoMAE 基线 | ✅ | ✅ | ✅ |
-| L1 有图 vs 无图先验 | ✅ | — | — |
-| L1 历史帧消融 | — | ✅ | — |
-| L1 belief 字段 probe | ✅ | ✅ | ✅ |
-| L2 语义干预 | ✅ | ✅ | ✅ |
-| L2 图像模态消融 | ✅ | ✅ | ✅ |
-| L2 模型消融（换 LLM） | ✅ | — | — |
-| L2 理由-决策对应（核心） | ✅ | ✅ | ✅ |
-| L1 延迟基准 / CLIP 诊断 | ✅ | — | — |
-
-¹ HK L1：连续角度 MAE 3.65° 正常，分桶头 `angle_bin` 因 1 个 center 样本塌缩为 0（死头，L2 compact 不使用，已标注）。
-
-基线口径：命题限定为「任务专训的小网 > 冻结的通用视觉特征（作为 belief 抽取器）」，数据/历史/考卷已对齐（balanced 全 boss、同历史、同考卷）。
-
-## 残留口径（非错误，诚实披露）
-- Isaac 的 L2 语义/理由**天生信号弱**（菜单小 K̄=2.83、随机基线高），主证据用 HK/VR。
-- 基线训练量 10k vs PACT 30k，饱和曲线待做。
-- L2 决策质量 LLM judge 暂缓（口径未定）。
-
-## 结构性防线
-五闸门接入 L2 shell（不过 exit 3 拒跑，含负对照）· run_config 记 sha256 血缘 · `balanced_limit` 全项目统一 · 入口默认对齐正典采样版 · registry 自校验。

docs/DATA.md

@@ -0,0 +1,83 @@
+# Data
+
+PACTBench expects the three game subsets distributed under the dataset
+identifier `teawhite/vrising`. Check the dataset card and its current terms
+before redistributing any raw game footage; this repository documents the
+layout used by the experiments but does not itself grant rights to third-party
+game content.
+
+## Processed layout
+
+```text
+data/processed/<Boss>/                 # V Rising
+data/hk/processed/<Boss>/              # Hollow Knight
+data/isaac/processed/<Boss>/           # Isaac
+
+<Boss>/
+├── video_fight<N>.mp4
+├── policy_view_fight<N>.jsonl
+├── render_view_fight<N>.jsonl
+└── dataset_manifest.json
+```
+
+Each `policy_view` row is a boss decision with an action and observation. Each
+`render_view` row supplies the aligned rendered prompt. Video, policy, and
+render files are audited together by boss and fight.
+
+## Fight-disjoint splits
+
+| Game | Bosses | Train fights | Validation fights | Test fights | Official test rows |
+|---|---:|---:|---:|---:|---:|
+| V Rising | 3 | 54 | 9 | 9 | 8,075 |
+| Hollow Knight | 3 | 484 | 9 | 30 | 8,360 |
+| Isaac | 8 | 4,858 | 24 | 80 | 1,784 |
+
+Splits operate on complete fights. No fight appears in more than one split.
+V Rising uses the last three fights per boss for test and the preceding three
+for validation. Hollow Knight and Isaac use the last ten fights per boss for
+test and the preceding three for validation.
+
+V Rising has two manifests:
+
+- `games/vrising/manifest.json` records the fight-level dataset split.
+- `games/vrising/manifest_latent_covered.json` is the canonical L1 training
+  manifest and retains only fights with the required visual coverage.
+
+## Observation fields and units
+
+Common policy observations include distance, angle, relative geometry,
+previous-action timing, fight time, and boss/player state. The exact schema is
+checked by the dataset audit and the belief validators.
+
+- V Rising and Hollow Knight distance use engine units.
+- Isaac `obs.dp` uses pixels (observed range 24--484; median about 147 px).
+- Isaac L1 therefore fixes `distance_norm=1000` and `distance_clamp=1.5`.
+
+## Build and audit
+
+Run from the `pactbench` root:
+
+```bash
+bash games/vrising/data/audit_dataset.sh
+bash games/vrising/data/build_manifest.sh
+
+bash games/hk/data/audit_dataset.sh
+python3 games/hk/data/build_metadata.py
+bash games/hk/data/build_manifest.sh
+
+bash games/isaac/data/audit_dataset.sh
+python3 games/isaac/data/build_metadata.py
+bash games/isaac/data/build_manifest.sh
+```
+
+The audit outputs are:
+
+```text
+results/vrising/dataset_audit.json
+results/hk/dataset_audit.json
+results/isaac/dataset_audit.json
+```
+
+HK and Isaac metadata are derived from the processed policy/render rows.
+V Rising uses the checked-in canonical `ontology.json` and
+`skill_library.json`.

docs/EXPERIMENTS.md

@@ -0,0 +1,170 @@
+# Experiments and Published Results
+
+This document describes the results published by
+`registry/registry.json`. Aggregate numbers are recomputed from the referenced
+artifacts by the full release gate.
+
+## Common protocol
+
+- Splits are fight-disjoint.
+- L1 consumes five causal RGB frames at offsets `[-8,-4,-2,-1,0]`.
+- L2 uses the compact belief interface and anonymous option IDs.
+- The L2 model is Gemma-4-E2B-it revision `70af34e...`, temperature 0.
+- balanced-v3 selects source states across boss, fight, and distance strata
+  before any L2 response is read.
+- The prompt conditions are full mechanics, no mechanics, and swapped
+  mechanics. The word `full` in a run name refers to the full-description
+  prompt, not the deprecated full belief view.
+
+## L1 official evaluation
+
+| Game | Test rows | Distance MAE | dp@2 | Angle MAE | angle@20° | Distance-bin acc. | Angle-bin acc. |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| V Rising | 8,075 | 0.2620 | 0.9960 | 11.7599° | 0.8293 | 0.8320 | 0.7201 |
+| Hollow Knight | 8,360 | 0.4680 | 0.9728 | 3.6527° | 0.9788 | 0.7261 | 0.9646 |
+| Isaac | 1,784 | 9.0263 px | 0.1519 | 29.6388° | 0.6211 | 0.9036 | 0.8352 |
+
+`dp@2` uses native distance units and is therefore not comparable between
+Isaac and the other games.
+
+## L1 matched-data visual comparison
+
+| Game | Method | Train rows | Distance MAE | Angle MAE | Distance-bin acc. | Angle-bin acc. |
+|---|---|---:|---:|---:|---:|---:|
+| V Rising | PACT-L1 | 18,068 | **0.2620** | **11.7599°** | **0.8320** | **0.7201** |
+|  | frozen DINOv2-S + probe | 18,068 | 0.6900 | 20.1532° | 0.6405 | 0.6041 |
+|  | frozen VideoMAE-B + probe | 18,068 | 0.6672 | 17.6564° | 0.6821 | 0.5948 |
+| Hollow Knight | PACT-L1 | 10,000 | **0.5671** | **4.0899°** | **0.6940** | **0.9560** |
+|  | frozen DINOv2-S + probe | 10,000 | 0.8641 | 20.0433° | 0.5542 | 0.8276 |
+|  | frozen VideoMAE-B + probe | 10,000 | 1.0017 | 27.5987° | 0.4544 | 0.7100 |
+| Isaac | PACT-L1 | 9,484 | **15.0472** | **39.6855°** | **0.8358** | **0.7848** |
+|  | frozen DINOv2-S + probe | 9,484 | 35.2852 | 77.7867° | 0.6015 | 0.6048 |
+|  | frozen VideoMAE-B + probe | 9,484 | 47.5451 | 84.9615° | 0.4608 | 0.5067 |
+
+Every three-way comparison uses the same ordered training rows, official test
+rows, resolution, and five-frame history within a game. PACT-L1 is task-trained
+end to end; the two foundation baselines freeze their pretrained backbone and
+train task probes. These results compare complete training schemes rather than
+isolating backbone architecture.
+
+### V Rising end-to-end DINOv2-S L1 comparison experiment
+
+This separate comparison makes the DINOv2-S backbone task-trainable and applies
+the same published V Rising rows, five-frame history, task heads/losses, seed,
+and two-stage 10+10 epoch schedule used by PACT-L1. Both methods are evaluated
+on the same ordered 8,075 official test rows.
+
+| Method | Parameters | Distance MAE | Angle MAE | Distance-bin acc. | Angle-bin acc. | A800 batch-1 latency |
+|---|---:|---:|---:|---:|---:|---:|
+| PACT-L1 | 13,040,742 | **0.2620** | **11.7599°** | **0.8320** | **0.7201** | **5.8497 ms** |
+| DINOv2-S end to end | 23,443,622 | 0.8566 | 24.8192° | 0.5771 | 0.5845 | 8.7039 ms |
+
+Under this matched recipe, DINOv2-S has 3.2695 times the distance error, 2.1105
+times the angle error, and 48.79% higher model-forward latency. The latency
+protocol uses AMP, 256 pre-decoded histories, 10 warm-up passes, and 20 measured
+repeats; it includes CPU-to-GPU transfer and model-specific preprocessing but
+excludes mp4 decoding. The measured 8.7039 ms is slower than PACT-L1 but does
+not establish failure of a 60 Hz real-time budget on this A800.
+
+The result does not mean that a larger pretrained model must be more accurate
+after fine-tuning. In this implementation, the most likely explanation is a
+training-recipe and spatial-interface mismatch:
+
+- The PACT learning-rate schedule uses one shared learning rate for the
+  pretrained DINO backbone and the newly initialized task heads. The frozen
+  DINO probe obtains 0.6900 distance MAE and 20.1532° angle MAE, while the first
+  end-to-end stage at learning rate 3e-4 degrades to 0.9128 and 24.7542°; the
+  second stage recovers distance only to 0.8566. This is evidence that the
+  copied schedule over-updates the current DINO adaptation, although it is not
+  a one-factor causal ablation.
+- The adapter retains one global CLS vector per frame and discards DINO patch
+  tokens. That removes localized spatial evidence that is useful for distance
+  and angle estimation.
+- The native 192x336 frame is stretched to DINO's 224x224 square input, changing
+  the geometry seen by the model.
+
+Accordingly, this experiment supports the conclusion that the evaluated
+end-to-end DINOv2-S configuration is worse than PACT-L1 under the matched PACT
+recipe. It is not a general upper bound on a DINOv2 system with separately
+validated backbone/head learning rates, patch-token readout, and
+aspect-ratio-preserving preprocessing. The machine-readable record is
+`results/vrising/eval_runs/L1-DINOV2-END-TO-END-MATCHED20/comparison.json`.
+
+## L2 semantic intervention
+
+Description-follow records whether the swapped-prompt decision follows the
+mechanics moved to another anonymous option rather than retaining the original
+option identity.
+
+### Natural-ready menus
+
+| Game | Valid pairs | Mean K | Chance | No-description change | Swap change | Description-follow |
+|---|---:|---:|---:|---:|---:|---:|
+| V Rising | 200 | 4.875 | 21.93% | 46.0% | 79.5% | **67.0%** |
+| Hollow Knight | 200 | 5.370 | 18.78% | 90.0% | 95.0% | **79.5%** |
+| Isaac | 122 | 2.238 | 46.04% | 56.6% | 85.2% | **83.6%** |
+
+The natural-ready menu is a deterministic benchmark tracker rule based on
+logged re-fire lower bounds and previous-action constraints. It is not an
+engine legality oracle. Isaac has fewer skills and smaller natural menus than
+the other games. Its 122 valid pairs are the predefined `menu>=2` subset of the
+200 source states, not a selection based on model success.
+
+### Fixed two-choice control
+
+| Game | Pairs | Chance | No-description change | Swap change | Description-follow |
+|---|---:|---:|---:|---:|---:|
+| Hollow Knight | 200 | 50.0% | 31.5% | 60.5% | 60.5% |
+| Isaac | 200 | 50.0% | 39.0% | 54.0% | 54.0% |
+
+The two-choice experiment is a fixed high-chance stress control. Hollow Knight
+is above its 50% reference; Isaac is close to it. The cross-game result is the
+eligible natural-ready intervention, while the two-choice table shows that the
+effect depends on candidate-space construction.
+
+## Image-modality diagnostic
+
+Text and text-plus-current-image conditions use the same states, prompt text,
+and inference parameters.
+
+| Game | Effective paired states | Text follow | Text + image follow | Original decision changed |
+|---|---:|---:|---:|---:|
+| V Rising | 60 | 60.0% | 65.0% | 21.7% |
+| Hollow Knight | 60 | 78.3% | 80.0% | 3.3% |
+| Isaac | 40 | 90.0% | 70.0% | 5.0% |
+
+The observed direction is not uniform across games. This diagnostic measures
+modality sensitivity and does not establish that adding an image always
+improves semantic control.
+
+## Prompt-visible rationale correspondence
+
+The deterministic audit checks whether the visible reason and mechanics cards
+support reconstruction of the model's selected option. It does not inspect a
+hidden chain of thought.
+
+| Game | Valid pairs | Normal support | No-description support | Shuffled-reason support |
+|---|---:|---:|---:|---:|
+| V Rising | 200 | 93.5% | 3.5% | 3.7% |
+| Hollow Knight | 200 | 94.5% | 0.0% | 2.6% |
+| Isaac | 122 | 74.6% | 31.1% | 48.2% |
+
+## Game-specific completed analyses
+
+- V Rising model ablation: description-follow is 67.0% for Gemma-4 E2B,
+  64.5% for Gemma-3n E2B, and 56.0% for Gemma-4 E4B. Model size is not
+  monotonic with this metric.
+- V Rising batch-8 latency on pre-decoded histories: PACT-L1 1.1440 ms,
+  frozen DINOv2-S + probe 4.3040 ms, and frozen VideoMAE-B + probe
+  20.4469 ms per decision. This benchmark excludes video decoding.
+- Hollow Knight current-frame ablation: on the fixed paired subset, distance
+  MAE changes from 0.5160 with five frames to 0.5478 with the current frame
+  only.
+
+## Decision-quality judge
+
+The semantic intervention measures whether decisions respond to visible skill
+mechanics. Tactical decision quality is a different question and is evaluated
+by the external menu-level judge described in
+`pipelines/l2/llm_judge/README.md`. External judge artifacts are not part of
+the local deterministic registry until explicitly reviewed and synchronized.

docs/EXPERIMENT_CHECKLIST.md

@@ -1,125 +0,0 @@
-# PACT Experiment Checklist
-
-Last updated: 2026-07-09 08:12:54 UTC
-
-This checklist tracks the current three-game experiment plan and the concrete
-artifacts that should exist before a result is considered complete.
-
-## Repository Layout
-
-| Item | Status | Path |
-|---|---|---|
-| Public game entry points | Done | `code/{vrising,hk,isaac}` |
-| Shared game configs | Done | `configs/games/{vrising,hk,isaac}.json` |
-| V Rising run commands | Done | `evaluation/ablations/pact_eval_v1_20260709/RUN_COMMANDS.md` |
-| V Rising status report | Done | `evaluation/ablations/pact_eval_v1_20260709/vrising_experiment_status.md` |
-
-## V Rising
-
-Priority: current primary game.
-
-| Area | Status | Artifacts / Notes |
-|---|---|---|
-| Dataset audit | Done | `out/eval_runs/vrising_dataset_audit.json` |
-| Split manifest | Done | `out/layered/manifest_vrising.json` |
-| L1 main comparison | Done | See `evaluation/ablations/pact_eval_v1_20260709/vrising_experiment_status.md` |
-| L1 image ablation | Done | `evaluation/ablations/pact_eval_v1_20260709/l1/` |
-| L1 latency | Done | `out/situation/l1_visual_latency_benchmark_b8.json` |
-| L2 semantic intervention, full belief view | Done | `out/eval_runs/20260709_L2_L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_full_full-no_desc-swap_seed0/metrics.json` |
-| L2 semantic intervention, compact belief view | Done | `out/eval_runs/20260709_L2_L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_compact_full-no_desc-swap_seed0/metrics.json` |
-| L2 decision quality with LLM judge | Deferred | Not planned on this machine for now |
-
-Current V Rising L2 full-view metrics:
-
-| Metric | Value |
-|---|---:|
-| n | 200 |
-| no-desc decision change rate | 0.4372 |
-| swap-desc decision change rate | 0.8782 |
-| swap desc follow rate | 0.7868 |
-| swap name bias rate | 0.1218 |
-
-Current V Rising L2 compact-view metrics:
-
-| Metric | Value |
-|---|---:|
-| n | 200 |
-| no-desc decision change rate | 0.5435 |
-| swap-desc decision change rate | 0.9022 |
-| swap desc follow rate | 0.8587 |
-| swap name bias rate | 0.0978 |
-
-V Rising sessions completed at 2026-07-09 05:25:41 UTC. The finalizer rebuilt
-the status report and stopped the Gemma service.
-
-Active download sessions:
-
-```bash
-tmux ls | rg 'pact_'
-tail -f out/eval_runs/20260709_hk_isaac_download.log
-```
-
-## Hollow Knight (`hk`)
-
-Priority: second game after V Rising L2 finishes or while data download is
-available.
-
-| Area | Status | Required Artifacts |
-|---|---|---|
-| Data download | Done | `data/hk/processed` -> `data/_hf_teawhite_vrising_hk_isaac/HK` |
-| Ontology | Done | `out/hk/ontology.json` |
-| Skill library | Done | `schemas/hk_skill_library.json` |
-| Dataset audit | Done | `out/eval_runs/hk_dataset_audit.json` |
-| Split manifest | Done | `out/hk/layered/manifest.json` |
-| L1 train/eval | Running: train30k cache + official test, then GPU2 training | `pact_hk_l1_train30k_gpu2`, log `out/hk/logs/20260709_hk_l1_train30k_gpu2.log` |
-| L2 semantic intervention | Blocked on L1 output and skill library | `code/hk/l2/run_semantic_views.sh` is a placeholder |
-
-Data-download owner: main process. The dataset repo is anonymously accessible.
-HK has 1,572 files across 3 entities. Dataset audit passed with zero warnings.
-The full HK train cache is 144,418 samples and about 130 GiB of raw uint8
-tensor data, so the active fast run uses a documented 30,000-sample train cache
-with the unchanged official test split. Treat this as `HK-L1 train30k`, not the
-final full-data HK result.
-
-Validation commands once data is available:
-
-```bash
-bash code/hk/data/audit_dataset.sh
-bash code/hk/data/build_manifest.sh
-```
-
-## The Binding of Isaac (`isaac`)
-
-Priority: third game after V Rising L2 finishes or while data download is
-available.
-
-| Area | Status | Required Artifacts |
-|---|---|---|
-| Data download | Downloading with low-concurrency resume | `data/_hf_teawhite_vrising_hk_isaac/Isaac`, then linked to `data/isaac/processed` |
-| Ontology | Missing | `out/isaac/ontology.json` |
-| Skill library | Missing | `schemas/isaac_skill_library.json` |
-| Dataset audit | Blocked on data | `out/eval_runs/isaac_dataset_audit.json` |
-| Split manifest | Blocked on data and ontology | `out/isaac/layered/manifest.json` |
-| L1 train/eval | Blocked on processed data | `code/isaac/l1/train_l1.sh` is a placeholder |
-| L2 semantic intervention | Blocked on L1 output and skill library | `code/isaac/l2/run_semantic_views.sh` is a placeholder |
-
-Data-download owner: main process. The dataset repo is anonymously accessible.
-Isaac has 14,894 files across 8 entities and an estimated size of 22.73 GB.
-The first high-concurrency download hit HF 429 rate limits, so the current
-session `pact_hk_isaac_download` resumes Isaac only with `--max-workers 2`.
-
-Validation commands once data is available:
-
-```bash
-bash code/isaac/data/audit_dataset.sh
-bash code/isaac/data/build_manifest.sh
-```
-
-## Current Blockers
-
-| Blocker | Impact | Owner / Next Action |
-|---|---|---|
-| `isaac` download is still running | Isaac audit, manifest, L1, and L2 wait for complete local files | Monitor `pact_hk_isaac_download` |
-| HK L1 train30k cache/training is running | HK L1 ablations and L2 handoff wait for training outputs | Monitor `pact_hk_l1_train30k_gpu2` |
-| `isaac` ontology and skill library are missing | Isaac manifest and L2 cannot run even if processed rows arrive without metadata | Derive or supply metadata after Isaac download |
-| Current GPUs are busy | Avoid starting extra heavy L1 jobs during large data download and existing cluster load | Queue heavy jobs after data audit succeeds |

docs/L2_EVAL_PLAN.md

@@ -1,103 +0,0 @@
-# L2 Evaluation Plan
-
-## Claim Map
-
-| Claim | What It Proves | Main Evidence |
-|---|---|---|
-| C1: L2 decisions are semantically controlled by skill mechanics. | The model reads skill descriptions instead of choosing from name/order priors. | Anonymous-ID skill-description intervention. |
-| C2: L2 rationales support the selected decision. | The emitted reason is aligned with the selected skill and grounded in L1 belief/mechanics. | Rationale reconstruction and contradiction checks. |
-| C3: L2 rationales are not detached post-hoc text. | The reason can reconstruct or explain the selected decision under the same mechanics setting. | Rationale reconstruction + swapped-description rationale follow. |
-
-## Paper Tables
-
-### Table L2-A: Decision Semantic Control
-
-Status: partially complete. Gemma-4 anonymous-ID result is complete at `n=200`.
-
-| Row | Setting | Metrics |
-|---|---|---|
-| Gemma-4-E2B-it | Anonymous IDs, full/no-desc/swapped desc. | No-Desc Flip, Desc-Follow, Name-Bias |
-| Gemma-3n-E2B-it | Same setting, rerun `n=200`. | Same metrics |
-| Gemma-4 original skill names | Optional appendix/control. Existing `n=30` is pilot only. | Same metrics |
-
-Use the current Gemma-4 row as the main result:
-
-| Setting | n | No-Desc Flip | Desc-Follow | Name-Bias |
-|---|---:|---:|---:|---:|
-| Gemma-4, anonymous IDs | 200 | 54.0 [47.1, 60.8] | 76.0 [69.6, 81.4] | 14.0 [9.9, 19.5] |
-
-Interpretation: `Desc-Follow` is the primary metric. `Name-Bias` is the control.
-
-### Panel L2-B: Rationale-Decision Consistency
-
-Status: complete for Gemma-4 anonymous-ID `n=200` rows.
-
-| Row | Setting | Metrics |
-|---|---|---|
-| Gemma-4-E2B-it | Anonymous IDs, full desc. | R->D Recon., Contradiction |
-| Gemma-4-E2B-it | Anonymous IDs, swapped desc. | R->D Recon., Rationale Desc-Follow, Contradiction |
-| Gemma-3n-E2B-it | Same as Gemma-4. | Same metrics |
-
-Definitions:
-
-- `R->D Recon.`: mask skill IDs in the rationale; an independent evaluator reconstructs the skill from rationale + L1 belief + menu.
-- `Rationale Desc-Follow`: under swapped descriptions, the rationale supports the swapped-in mechanics rather than the original skill meaning.
-- `Contradiction`: rationale contradicts L1 belief, cooldown, or selected mechanics.
-
-This table is the formal answer to whether reasoning and decision are aligned.
-
-## Ablations
-
-### Must-Run Ablations
-
-1. **Model ablation: Gemma-4 vs Gemma-3n**
-   - Same `n=200`, anonymous IDs, temperature 0.
-   - Metrics: No-Desc Flip, Desc-Follow, Name-Bias, R->D Recon., Reason Ground.
-   - Purpose: show whether the stronger LLM improves semantic control and rationale alignment.
-
-2. **Description ablation: full vs no-desc vs swapped**
-   - Already done for Gemma-4 decisions.
-   - Needs rationale-side evaluation.
-   - Purpose: this is the core reasoning intervention.
-
-3. **Name leakage control: original names vs anonymous IDs**
-   - Original names can be appendix unless rerun at `n=200`.
-   - Purpose: show results do not come from skill-name priors.
-
-4. **L1 belief ablation for rationale grounding**
-   - Full L1 belief vs no distance vs no cooldown vs no previous skill.
-   - Metrics: R->D Recon., Reason Ground., Contradiction.
-   - Purpose: verify rationales use L1 information and fail gracefully when fields are removed.
-
-### Nice-to-Have Ablations
-
-1. **Temperature robustness**
-   - `temperature=0` vs `0.3`, 3 seeds if stochastic.
-   - Use appendix only.
-
-2. **Evaluator robustness**
-   - Rule evaluator vs LLM evaluator for rationale checks.
-   - Use appendix to defend metric reliability.
-
-3. **Per-boss failure analysis**
-   - StoneBreaker needs qualitative inspection because `Desc-Follow=48.5%` and `Name-Bias=38.2%`.
-   - Output: 4-6 examples showing ambiguous or overlapping mechanics.
-
-## Run Order
-
-| Priority | Run | Output |
-|---|---|---|
-| 1 | Implement rationale evaluator on existing Gemma-4 `n=200` rows. | DONE: `out/layered/l2_rationale_consistency_gemma_anon_n200.json` |
-| 2 | Run Gemma-3n intervention at `n=200` anonymous IDs. | Table L2-A Gemma-3n row |
-| 3 | Run Gemma-3n rationale evaluator. | Table L2-B Gemma-3n rows |
-| 4 | Optional: rerun original-name Gemma-4 at `n=200`. | Appendix name-leakage control |
-| 5 | StoneBreaker failure analysis. | Appendix qualitative analysis |
-
-## Main-Paper Recommendation
-
-Main paper should contain:
-
-1. One formal L2 table with panel (a) semantic-control intervention and panel (b) rationale-decision consistency.
-2. Gemma-3n as a model ablation in the same table after it is rerun.
-
-CLIP cosine should remain auxiliary/appendix only.

docs/MAINTAINERS.md

@@ -0,0 +1,88 @@
+# Maintainer Handoff and Release Procedure
+
+## Sources of truth
+
+Use this order when resolving conflicting information:
+
+```text
+published row-level artifacts and metrics
+    > registry/registry.json
+    > docs/EXPERIMENTS.md
+    > root and game READMEs
+```
+
+Documentation does not promote an experiment. Promotion happens only through
+an accepted artifact set and a passing registry build.
+
+## Review isolation
+
+Store an unreviewed run under:
+
+```text
+experiments/pending_review/<run_id>/
+├── PLAN.md
+├── RUN_CONFIG.json
+├── metrics.json
+├── run.log
+└── REVIEW.md
+```
+
+Before `REVIEW.md` records `Decision: ACCEPT`, the run must not:
+
+- update `registry/registry.json`;
+- replace a published checkpoint or metric file;
+- change headline tables in release documentation;
+- enter a paper abstract, table, or conclusion;
+- be described as a PACTBench result.
+
+An accepted review should identify the exact claim, baseline, data rows,
+checkpoint, seed, metric implementation, latency boundary if applicable, and
+the artifact paths to publish.
+
+## Adding or updating an experiment
+
+1. Fix the question, comparison, sample set, metrics, and acceptance rule before
+   reading the new output.
+2. Use a game wrapper under `games/<game>/` and shared implementation under
+   `pact/` or `pipelines/`.
+3. Write ordered rows, run configuration, model identity, source identities,
+   and aggregate metrics.
+4. Add focused regression tests for new provenance or metric rules.
+5. Run unit tests and the full artifact gate.
+6. Review the artifacts and record the decision.
+7. Update `registry/build_registry.py` if a new published field is required.
+8. Run `python3 registry/build_registry.py`; never hand-edit the generated
+   registry.
+9. Update only the relevant current documentation.
+
+## Adding a game
+
+A game release requires:
+
+- `games/<game>/config.json`, `ontology.json`, `skill_library.json`, and a
+  fight-level manifest;
+- processed video, policy, render, and dataset-manifest alignment;
+- L1 train/eval wrappers and a published checkpoint with strict provenance;
+- a compact L1 handoff consumed by L2;
+- deterministic L2 source-state selection and row-level outputs;
+- registry entries and full-gate validation;
+- one game README containing only game-specific paths and parameters.
+
+## Release checklist
+
+- All current Markdown links and literal commands resolve.
+- Python files parse and shell files pass `bash -n`.
+- Regression tests pass with bytecode generation disabled.
+- `python3 pact/validate_pactbench.py --require_v5` passes.
+- `python3 registry/build_registry.py` succeeds atomically.
+- Published numbers match the rebuilt registry and metric files.
+- No private absolute paths, credentials, internal reviews, backups, or meeting
+  materials are included in the release package.
+- Data redistribution terms, repository license, citation metadata, and author
+  information have been approved by the maintainers.
+
+## Current external boundary
+
+The decision-quality judge runs on a separate machine. Its credentials and
+deployment are not part of the local release gate. Synchronize only reviewed
+judge rows, configuration, and summaries; never copy service credentials.

docs/MIGRATION.md

@@ -1,69 +0,0 @@
-# 迁移记录（2026-07-13）
-
-把三游戏 L1/L2 主线从旧 `pact/` 的散装结构（`code/` + `scripts/` + `evaluation/` + `out/` + `schemas/` + `configs/` + `experiments/`）
-收敛成自包含的 `pactbench/`。之后所有实验在 `pactbench/` 里做。
-
-## 原则
-
-- **代码、ckpt、指标是真文件，搬进来**（加起来 < 400 MB）。
-- **数据和 RGB cache 是软链**（165 G，且 cache 可分钟级重建），不复制。
-- **每个被搬走的旧位置都留了一个软链回指新位置** —— 留在旧 pact 的 65 个 legacy 脚本（渲染 / 闭环 / 画图）
-  有 15 个反向 import 了主线模块，靠这些回链继续工作。所以这次迁移**没有破坏任何旧代码**。
-
-## 路径映射
-
-| 旧位置 | 新位置 |
-|---|---|
-| `scripts/{33 个主线 py}` | `pact/` |
-| `src/layered_belief.py` | `pact/layered_belief.py` |
-| `scripts/deprecated/` | `pact/deprecated/` |
-| `evaluation/ablations/*/scripts/{5 个消融 py}` | `pact/` |
-| `code/{game}/{data,l1,l2}/*.sh` | `games/{game}/{data,l1,l2}/*.sh` |
-| `evaluation/l1/{train,eval,baselines}/*.sh` | `pipelines/l1/{train,eval,baselines}/` |
-| `evaluation/ablations/pact_eval_v1_20260709/l2/*.sh` | `pipelines/l2/` |
-| `evaluation/l2/llm_judge_package/` | `pipelines/l2/llm_judge/` |
-| `configs/games/{game}.json` | `games/{game}/config.json` |
-| `schemas/{,hk_,isaac_}skill_library.json` | `games/{game}/skill_library.json` |
-| `out/{game}/ontology.json` | `games/{game}/ontology.json` |
-| `out/{game}/layered/manifest.json` | `games/{game}/manifest.json` |
-| `out/{game}/situation/*.pt`（ckpt） | `ckpt/{game}/l1_*.pt`（**重命名为可读名字**） |
-| `out/{game}/situation/*_official_test.json{,l}` | `results/{game}/l1_*.json`、`beliefs_*.jsonl` |
-| `out/{game}/eval_runs/` | `results/{game}/eval_runs/` |
-| `out/eval_runs/{game}_dataset_audit.json` | `results/{game}/dataset_audit.json` |
-| `evaluation/ablations/{img_input_20260708,pact_eval_v1_20260709}/` | `results/vrising/ablations/` |
-| `experiments/{registry.json,build_registry.py,status.py}` | `registry/` |
-
-ckpt 重命名对照：
-
-| 旧文件名 | 新文件名 |
-|---|---|
-| `raw_rgb_resnet18_decision_finetune_from_dp_current0_e10.pt` | `ckpt/vrising/l1_main_resnet18_e10.pt` |
-| `raw_rgb_resnet18_decision_train30k_from_dp_current0_e10.pt`（hk） | `ckpt/hk/l1_main_train30k_e10.pt` |
-| `hk_l1_curframeonly_e10.pt` | `ckpt/hk/l1_ablation_curframeonly_e10.pt` |
-| `isaac_l1_fixed_e10.pt` | `ckpt/isaac/l1_main_fixed_e10.pt` |
-| `isaac_l1_norm_e10.pt` | `ckpt/isaac/l1_variant_norm_e10.pt` |
-| `raw_rgb_resnet18_decision_train30k_from_dp_current0_e10.pt`（isaac） | `ckpt/isaac/l1_DEPRECATED_broken_default_norm_e10.pt` |
-
-## 没搬的
-
-- **V Rising 的 L3/L4 闭环与世界模型**：`../src/{closed_loop,closed_loop_ar,skill_recognizer,teacher,decision_head,render*}.py`、
-  `../scripts/render_*.py`、`../out/closed_loop_*`。这批代码有十几处硬编码绝对路径（依赖 BoranTencent、DAR 的 Wan 权重），
-  7-02 后没再动过，属于另一条线。
-- **画图 / 论文 / PPT**：`../figures_*`、`../paper/`、`../standardslide/`、`../scripts/build_l1_*_assets.py` 等。
-- **data/ 与 RGB cache**：原地，通过 `pactbench/{data,out}` 软链访问。
-
-## 校验
-
-迁移后已验证：
-
-1. `python3 registry/build_registry.py` —— **逐条核验新布局下每个路径真的存在**，通过 ✅
-2. `python3 registry/status.py` —— 状态表正常输出
-3. 三个游戏的 `games/{game}/data/audit_dataset.sh` **真跑通**，产物落在 `results/{game}/dataset_audit.json` ✅
-4. 旧路径（如 `../out/hk/eval_runs/`、`../scripts/train_rgb_situation_net.py`）经回链仍可读 ✅
-
-## 遗留
-
-- `pipelines/l2/{run_official_rationale_eval.sh, llm_judge/*.sh}` 和
-  `pipelines/l1/baselines/retrain_foundation_probes_from_cache.sh` 仍引用 `out/layered/…` 下的
-  legacy V Rising 中间产物（predictions / latent-covered manifest）。经 `out` 软链可用，但没有归位到 `results/`。
-  这几个脚本都属于「L2 决策质量评价（暂缓）」和 latent 时代的旧线，等真要用时再收拾。

docs/OLD_experiments_README.md

@@ -1,149 +0,0 @@
-# PACT 实验目录（三个游戏）
-
-这是实验的**唯一权威索引**：数据怎么造的 → 做了哪些实验 → 对应哪个 ckpt → 对应哪段代码。
-之后的新实验直接在这里登记，不要另起炉灶。
-
-- **`registry.json`** — 机器可读的全量索引。每个实验绑定它的数据、代码、ckpt、指标。
-- **`build_registry.py`** — 生成上面那个文件。**每条路径都会核验是否真的存在于磁盘，每个数字都从它声称的 metrics 文件里重新读出来**。查无此文件就报错退出，索引因此不可能和实际跑过的东西脱节。
-
-改了实验后重新生成：
-
-```bash
-python3 experiments/build_registry.py
-```
-
----
-
-## 1. 数据是怎么构造的
-
-三个游戏共用同一套流程与同一套 `obs` schema（`dp` / `da` / `rel_angle` / `time_since` / `boss_hp_frac` / …）。
-
-```
-data/{game}/processed/{Boss}/
-    dataset_manifest.json
-    policy_view_fight{N}.jsonl     ← 决策行：action + obs
-    render_view_fight{N}.jsonl     ← 渲染 prompt（技能机制描述的来源）
-    video_fight{N}.mp4             ← 对应视频
-```
-
-| 步骤 | 代码 | 产物 |
-|---|---|---|
-| 1. 数据审计 | `code/{game}/data/audit_dataset.sh` | `results/vrising/eval_runs/{game}_dataset_audit.json` |
-| 2. ontology + 技能库 | `code/{game}/data/build_metadata.py` | `out/{game}/ontology.json`、`schemas/{game}_skill_library.json` |
-| 3. fight 级切分 manifest | `code/{game}/data/build_manifest.sh` | `out/{game}/layered/manifest.json` |
-| 4. RGB cache | `pact/build_rgb_frame_cache.py --workers 32` | `out/{game}/situation/raw_rgb_*.pt` |
-
-**切分规则**：fight 级。每个 boss 按 fight 排序，**最后 10 场作 test、前 3 场作 val、其余作 train**。
-切分单位是整场对局，所以训练/测试之间不存在同一场内的帧泄漏（每个游戏都已逐行核验，零越界样本）。
-
-**技能机制描述的来源**：`render_view` 里的 prompt 短语（"boss_1 performs …"），
-而不是人手编的。冷却/时长统计直接来自 `policy_view` 的日志行。
-`build_metadata.py` 里只有 `MECHANICS` 表是每游戏特有的，其余推导逻辑共享于
-`pact/build_game_metadata.py`。
-
-**RGB cache 必须并行建**：`--workers 32`。串行版建一个 8,360 样本的 cache 要约 2.5 小时，
-并行版 138 秒（结果逐字节一致，已验证）。默认 `--workers 1` 保留原行为。
-
-### 三个游戏的切分规模
-
-| 游戏 | boss 数 | 总 fight | train / val / test | 官方测试行数 |
-|---|---|---|---|---|
-| V Rising | 3 | — | 18,068 训练行 | 8,075 |
-| Hollow Knight | 3 | 523 | 484 / 9 / 30 | 8,360 |
-| Isaac | 8 | 4,962 | 4,858 / 24 / 80 | 1,784 |
-
----
-
-## 2. 做了哪些实验
-
-`canonical: true` 的是**当前对外引用的那一版**。其余是消融或已废弃的历史版本，登记但不引用。
-
-### L1（局势理解）
-
-| 实验 id | 游戏 | ckpt | 说明 |
-|---|---|---|---|
-| `vrising-L1-main` ★ | V Rising | `ckpt/vrising/l1_main_resnet18_e10.pt` | 主结果 |
-| `hk-L1-main` ★ | HK | `ckpt/hk/l1_main_train30k_e10.pt` | 主结果，5 帧输入 |
-| `hk-L1-ablation-single-frame` | HK | `ckpt/hk/l1_ablation_curframeonly_e10.pt` | 消融：只输入当前帧 |
-| `isaac-L1-main` ★ | Isaac | `ckpt/isaac/l1_main_fixed_e10.pt` | 主结果，**修复量纲 bug 后** |
-| `isaac-L1-broken-default-norm` | Isaac | `out/isaac/situation/raw_rgb_resnet18_decision_train30k_from_dp_current0_e10.pt` | **已废弃**，保留作 bug 证据 |
-
-### L2（技能机制语义干预）
-
-统一协议：**compact 视图 + gemma-4-E2B-it + 温度 0 + 200 个分层状态 + 匿名技能 ID**，
-三种 prompt：完整 / 抹除描述 / 交换描述。
-
-| 实验 id | 游戏 | 产物目录 |
-|---|---|---|
-| `vrising-L2-compact` ★ | V Rising | `results/vrising/eval_runs/…_compact_samplev2_…/` |
-| `vrising-L2-full` | V Rising | `results/vrising/eval_runs/…_full_samplev2_…/`（消融对照） |
-| `hk-L2-compact` ★ | HK | `results/hk/eval_runs/…_compact_test10_samplev2_…/` |
-| `isaac-L2-compact` ★ | Isaac | `results/isaac/eval_runs/…_compact_samplev2_…/` |
-
-每个 L2 run 目录含三件套：`metrics.json` / `rows.jsonl` / `run_config.json`（溯源）。
-
----
-
-## 3. 代码在哪
-
-结构是**薄壳 → 正典 → 实现**三层，三个游戏完全同构：
-
-```
-code/{game}/{data,l1,l2}/*.sh    ← 150–190 字节薄壳，只做 cd ROOT + 调用正典
-        ↓
-pipelines/l1/train/*.sh                              ← L1 正典
-pipelines/l2/*.sh    ← L2 正典
-        ↓
-pact/                                              ← 共享实现
-```
-
-| 用途 | 入口（跑这个） |
-|---|---|
-| L1 训练 | `CUDA_VISIBLE_DEVICES=<gpu> bash code/{game}/l1/train_l1.sh` |
-| L1 从 ckpt 评测 | `bash code/{game}/l1/eval_official_from_ckpt.sh` |
-| L2 语义干预 | `bash code/{game}/l2/run_semantic_views.sh` |
-
-L2 需要先起 gemma server（`gemma4-venv` 环境，默认 `http://127.0.0.1:8018/v1`）。
-
-**核心实现**：
-- `pact/train_rgb_situation_net.py` — L1 训练/评测
-- `pact/build_rgb_frame_cache.py` — RGB cache（`--workers` 并行）
-- `pact/build_game_metadata.py` — 共享的 ontology/技能库推导
-- `pact/eval_l2_skill_description_intervention.py` — L2 语义干预
-- `pact/write_l2_run_config.py` — L2 溯源记录
-
-已废弃的脚本在 `pact/deprecated/`，附说明。
-
----
-
-## 4. 两个必须知道的坑
-
-**① 距离量纲是每游戏不同的。**
-`obs.dp` 在 V Rising / HK 是引擎单位（0–15），在 Isaac 是**像素**（24–484，中位数 147）。
-训练脚本原先把归一化常数写死为 30、并把预测 clamp 在 `1.5 × 30 = 45`——
-**任何 dp > 45 的游戏，预测都会被静默压平在 45**（Isaac 实测预测中位数 45.0，真值 146.5）。
-
-现已提为 CLI 参数，默认值不变（V Rising / HK 零影响）：
-
-```bash
---distance_norm 1000.0 --distance_clamp 1.5     # Isaac 必须这样
-```
-
-**接入第四个游戏时，先看它的 `obs.dp` 分布再定 `distance_norm`。**
-
-**② L2 的分层采样曾经是坏的（v1）。**
-`choose_rows` 原先只按 `(boss, dp_bin)` 分桶，而行是按 fight 排序的，
-于是 200 个状态**全部塌缩到每个 boss 的第一场**。v1 的数字被高估。
-现已改为按 `(boss, fight, dp_bin)` 分层，`sample_set_id` 升为 **`L2-SAMPLE-200-v2`**。
-**只引用 v2 的结果。**
-
----
-
-## 5. 已知缺口
-
-- **HK 的 `player_angle_bin` 分类头 acc = 0.0000**（连续角度 3.65° 正常）。是这个 bin 头本身坏了，**未修**。
-  不影响 L2（compact 视图不含该字段）。同一个头在 V Rising 是 0.72、Isaac 是 0.79。
-- **V Rising 的 RGB cache 已被磁盘写满时清除**。ckpt / beliefs / metrics 都在，**L2 仍可复现**；
-  重跑 L1 评测需先从 `data/processed`（38G，完好）重建 cache。
-- HK / Isaac 未做：L1 视觉基线对比、belief probe、L2 图像模态消融（V Rising 已做）。
-- L2 决策质量的评价口径未定（LLM judge 在另一台机器进行）。

docs/README.md

@@ -1,75 +0,0 @@
-# Layered Evaluation Code Layout
-
-This directory is the normalized entry point for layer-by-layer evaluation.
-It does not replace the historical `scripts/` and `out/` files.  Instead, each
-layer directory records the canonical code paths, artifacts, commands, metrics,
-and paper-table sources needed to reproduce and audit that layer.
-
-The reusable experiment protocol lives in `exp.md`. It defines the default
-train/test/sample settings for current and future L1/L2 experiments.
-
-## Standard Layer Package
-
-Each layer should follow the same structure:
-
-```text
-evaluation/
-  l1/
-    README.md          # layer-specific story, metrics, and canonical commands
-    registry.json      # machine-readable map from names to scripts/artifacts
-    model/             # model definitions or pointers to canonical source files
-    train/             # training entry points, configs, and split notes
-    eval/              # official evaluation commands and metric definitions
-    baselines/         # comparison baselines and baseline-specific notes
-    ckpt/              # checkpoint manifest; large ckpts stay under out/ or data/
-    results/           # canonical result manifests; large outputs stay under out/
-```
-
-The same layout should be used for `l2/`, `l3/`, and `l4/`.
-
-## Storage Rules
-
-1. Keep implementation code in one canonical place.  If an old script is still
-   the source of truth, reference it here instead of copying it.
-2. Do not move large artifacts after paper tables have been generated.  Store
-   their paths and provenance in `registry.json`.
-3. Separate smoke outputs from official outputs.  Smoke files must not be used
-   in paper tables.
-4. Record train split, test split, input modality, checkpoint, and latency
-   definition for every paper-table row.
-5. A result used in a paper table must have:
-   - a JSON/CSV metric file,
-   - the exact script or wrapper that produced it,
-   - the checkpoint or frozen feature cache used,
-   - whether video decoding is included in latency.
-
-## Naming Rules
-
-Use compact, stable names:
-
-```text
-{layer}_{method}_{split}_{scope}.{ext}
-l1_pact_official_test.json
-l1_dinov2_covered_train_official_test.json
-l1_latency_b8.json
-```
-
-Prefer relative paths from the repository root in docs and registries.  Use
-absolute paths only in final responses or when needed by external tools.
-
-## Metric Categories
-
-Layer evaluations should separate:
-
-- **Primary task metrics**: the values that support the paper claim.
-- **Interface checks**: schema validity, legality, handoff compatibility.
-- **Runtime metrics**: model-forward latency and throughput, with a clear note
-  on whether decoding/rendering is included.
-- **Ablation/baseline metrics**: comparisons that isolate design choices.
-
-## Paper Table Policy
-
-Main paper tables should be numeric and compact.  Captions may describe split
-alignment and latency definitions, but table cells should not contain long
-explanations.  Put narrative interpretation in the text or in layer README
-files.

docs/REPRODUCE.md

@@ -1,100 +1,155 @@
-# 跨机器复现指南（打包清单）
+# Reproducing the Published PACTBench Snapshot
 
-审计日期 2026-07-14。结论：**pactbench 可以整体打包到另一台机器复现**——代码对旧 pact 无真实依赖
-（已验证：把 `src`/`out`/`data` 三个软链全部断开，9 个主线模块 import 全部从 `pact/` 自身解析成功）。
+Run all commands from the `pactbench` directory.
 
-## 1. 打包什么
+## 1. Environment
 
 ```bash
-cd pact
-tar czf pactbench_$(date +%Y%m%d).tar.gz \
-    --exclude='pactbench/data' --exclude='pactbench/out' --exclude='pactbench/src' \
-    --exclude='__pycache__' pactbench/
-# ≈ 400 MB：代码 + 6 个 ckpt + 全部 metrics/beliefs/eval_runs + registry + 文档
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+python3 -m pip install -r requirements.txt
 ```
 
-三个软链（`data`/`out`/`src`）**不打包**：`data` 在新机器重新下载（见 §3），`out` 全是可重建 cache，
-`src` 是旧 pact 的 L4 闭环代码——主线不需要（几个脚本里的 `sys.path.insert(ROOT/"src")` 是历史残留死代码）。
+The checked-in environment was validated with Python 3.13 and CUDA 12.x. The
+L1 path uses the versions pinned in `requirements.txt`.
 
-## 2. 新机器上的环境
+Gemma serving uses a separate environment because the server requires a newer
+Transformers release than the L1 environment:
 
 ```bash
-pip install -r requirements.txt        # 主环境（L1 + L2 客户端 + 数据构建）
-# gemma server 独立 venv（transformers 5.x 才有 Gemma4 类）——见 requirements.txt 尾部注释
+python3 -m venv .venv-gemma
+.venv-gemma/bin/python -m pip install \
+  "transformers==5.13.0" "torch==2.5.1" accelerate pillow
 ```
 
-会自动从 HF 下载的权重（无需手动搬）：
-| 权重 | 用途 | 来源 |
-|---|---|---|
-| `google/gemma-4-E2B-it` | L2 决策器 | HF（或设 `GEMMA_MODEL_PATH` 指本地快照）|
-| `vit_small_patch14_dinov2.lvd142m` | L1 视觉基线 | timm/HF |
-| `MCG-NJU/videomae-base` | L1 视觉基线 | HF |
-| torchvision ResNet-18 (ImageNet) | L1 主模型 backbone | torchvision |
+## 2. Data and caches
 
-## 3. 数据
+Make `data` point to the directory containing the processed layouts documented
+in `docs/DATA.md`. The repository currently uses:
 
-三个游戏的原始数据都在同一个 HF 数据集 **`teawhite/vrising`**（HK/Isaac 子目录）：
+```text
+data -> ../data
+out  -> ../out
+```
+
+Audit the available datasets before evaluation:
 
 ```bash
-mkdir -p data
-python pact/download_isaac.py          # 走 hf-mirror，绕开 snapshot_download 的 HEAD 风暴（见脚本头注释）
-# V Rising 的 processed（38G）同 repo；HK/Isaac 下载后按 games/{g}/config.json 的 processed_root 摆放
+bash games/vrising/data/audit_dataset.sh
+bash games/hk/data/audit_dataset.sh
+bash games/isaac/data/audit_dataset.sh
 ```
 
-期望的目录形状（`data` 可以是软链）：
+RGB caches are rebuildable from processed videos:
+
+```bash
+python3 pact/build_rgb_frame_cache.py --workers 32
 ```
-data/processed/{StoneBreaker,MilitiaLeader,ToadKing}/     # vrising
-data/hk/processed/{FalseKnight,HiveKnight,Hornet}/
-data/isaac/processed/{Dingle,...,Pin}/                    # 8 boss
-每个 boss 下: policy_view_fight{N}.jsonl + render_view_fight{N}.jsonl + video_fight{N}.mp4
+
+The canonical cache paths and their content identities are recorded in the
+published registry. The full gate rejects missing, stale, or mismatched caches.
+
+## 3. L1 evaluation
+
+Evaluate the published checkpoints:
+
+```bash
+bash games/vrising/l1/eval_official_from_ckpt.sh
+bash games/hk/l1/eval_official_from_ckpt.sh
+bash games/isaac/l1/eval_official_from_ckpt.sh
 ```
 
-## 4. ckpt ↔ 实验 ↔ 数据 setting 对照
+Run the matched frozen-foundation comparisons:
 
-| ckpt（打包内）| 游戏 | 训练 setting | 对应评测入口 |
-|---|---|---|---|
-| `ckpt/vrising/l1_main_resnet18_e10.pt` | V Rising | train 18,068 行；`distance_norm=30`（默认）；5 帧史 [-8,-4,-2,-1,0] 192×336 | `games/vrising/l1/eval_official_from_ckpt.sh`（需先重建 RGB cache）|
-| `ckpt/hk/l1_main_train30k_e10.pt` | HK | train 30,000 行；`distance_norm=30`；同 5 帧史 | `games/hk/l1/eval_official_from_ckpt.sh` |
-| `ckpt/hk/l1_ablation_curframeonly_e10.pt` | HK | 同上但 `history_offsets=0`（仅当前帧）| 历史帧消融对照 |
-| `ckpt/isaac/l1_main_fixed_e10.pt` | Isaac | train 26,984 行；**`distance_norm=1000 --distance_clamp 1.5`（必须）** | `games/isaac/l1/eval_official_from_ckpt.sh`（shell 已内置该参数）|
-| `ckpt/isaac/l1_variant_norm_e10.pt` | Isaac | 归一化变体 | 备用 |
-| `ckpt/isaac/l1_DEPRECATED_broken_default_norm_e10.pt` | Isaac | ❌ 量纲 bug 证据，勿引用 | — |
+```bash
+bash games/vrising/l1/run_foundation_baselines.sh
+bash games/hk/l1/run_foundation_baselines.sh
+bash games/hk/l1/run_matched_foundation10k.sh
+bash games/isaac/l1/run_foundation_baselines.sh
+```
+
+Run the accepted V Rising end-to-end DINOv2-S L1 comparison experiment:
+
+```bash
+bash games/vrising/l1/run_dinov2_end_to_end.sh
+```
 
-数据切分（fight 级、无帧泄漏，manifest 已打包在 `games/{g}/manifest.json`）：
-| 游戏 | train/val/test fights | 官方测试行数 | L2 随机基线 |
-|---|---|---|---|
-| V Rising | 54 / 9 / 9 | 8,075 | 22.4% (K̄=4.86) |
-| HK | 484 / 9 / 30 | 8,360 | 29.2% (K̄=3.42) |
-| Isaac | 4,858 / 24 / 80 | 1,784 | 35.3% (K̄=2.83) |
+The wrapper preserves accepted artifacts unless `FORCE_RERUN=1` is set and
+writes the canonical metrics, batch-1 latency, and comparison summary under
+`results/vrising/eval_runs/L1-DINOV2-END-TO-END-MATCHED20/`.
 
-## 5. 复现的三个层级（由浅入深）
+Isaac's matched PACT checkpoint is produced by
+`pipelines/l1/train/run_isaac_matched_after_weight_selection.sh` after the
+validation-only distance-weight selection. Published checkpoints and metrics
+can be validated without retraining them.
 
-**L0 — 不跑任何模型即可核验**：`python3 registry/build_registry.py`（逐条核验路径+从 metrics 重读数字）；
-所有正式数字都在 `results/{game}/`，`registry/registry.json` 是总账。
+The image-input controls are:
 
-**L1 级 — 只需 GPU + 数据**：
 ```bash
-source env.sh
-bash games/{g}/data/audit_dataset.sh && python3 games/{g}/data/build_metadata.py && bash games/{g}/data/build_manifest.sh
-python3 pact/build_rgb_frame_cache.py --workers 32 ...          # 重建 RGB cache（分钟级）
-CUDA_VISIBLE_DEVICES=<idle> bash games/{g}/l1/eval_official_from_ckpt.sh    # 从打包 ckpt 复现 L1 表
-bash games/{g}/l1/run_img_ablation.sh                            # 无图先验（CPU 秒级，读打包的 metrics 即可跑）
-bash games/{g}/l1/run_belief_probe.sh                            # belief 字段筛选（CPU 分钟级）
-bash games/{g}/l1/run_foundation_baselines.sh                    # 视觉基线（抽特征较慢，自动 cache）
+bash games/vrising/l1/run_img_ablation.sh
+bash games/hk/l1/run_img_ablation.sh
+bash games/isaac/l1/run_img_ablation.sh
 ```
 
-**L2 级 — 额外需要 gemma server**：
+## 4. L2 service and evaluation
+
+Start the pinned Gemma service with a local path or compatible model ID:
+
 ```bash
-CUDA_VISIBLE_DEVICES=<idle> GEMMA_PORT=8018 gemma4-venv/bin/python pact/gemma_server.py &
-bash games/{g}/l2/run_semantic_views.sh              # compact+full；--resume 会先逐位复现已打包的 rows
-bash games/{g}/l2/run_image_modality_ablation.sh     # 图像模态（60 状态配对）
+export GEMMA_MODEL_PATH=/path/to/gemma-4-E2B-it/revision-70af34e
+export GEMMA_PORT=8018
+.venv-gemma/bin/python pact/gemma_server.py
 ```
-L2 的输入 beliefs（`results/{g}/beliefs_l1_main_official_test.jsonl`）已打包，**不重训 L1 也能复现全部 L2 实验**。
 
-## 6. 已知坑（新机器必读）
+In another shell:
+
+```bash
+export GEMMA_OPENAI_BASE_URL=http://127.0.0.1:8018/v1
+export GEMMA_MODEL=gemma-4-E2B-it
+export GEMMA_TEMPERATURE=0
+
+bash games/vrising/l2/run_semantic_views.sh
+bash games/hk/l2/run_semantic_views.sh
+bash games/isaac/l2/run_semantic_views.sh
+```
+
+Rationale correspondence and paired image-modality runs use:
+
+```bash
+bash games/vrising/l2/run_rationale_consistency.sh
+bash games/hk/l2/run_rationale_consistency.sh
+bash games/isaac/l2/run_rationale_consistency.sh
+
+bash games/vrising/l2/run_image_modality_ablation.sh
+bash games/hk/l2/run_image_modality_ablation.sh
+bash games/isaac/l2/run_image_modality_ablation.sh
+```
+
+The Hollow Knight and Isaac fixed two-choice controls are selected through the
+game wrapper environment variables documented in their game READMEs.
+
+## 5. Verify the release
+
+```bash
+python3 registry/status.py
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
+python3 pact/validate_pactbench.py --require_v5
+```
+
+The current published snapshot passes 46 regression tests and 7,382 full-gate
+checks. To rebuild the machine-readable registry after an accepted change:
+
+```bash
+python3 registry/build_registry.py
+```
+
+The builder reruns the full gate before atomically replacing
+`registry/registry.json`. Do not edit the registry by hand.
+
+## 6. External decision-quality judge
 
-1. **Isaac 距离是像素量纲**：任何训练/评测/基线都必须 `--distance_norm 1000`（相关 shell 已内置，手写命令别忘）。
-2. **gemma server 必须用 transformers 5.x 的独立 venv**；主环境 4.51 没有 Gemma4 类。
-3. **不要依赖 `${GROUPS:-...}` 这类 shell 默认值**：有的机器预设了 `GROUPS` 环境变量（本机就是 `GROUPS=1000`）。
-4. HK 的 `player_angle_bin` 分类头恒输出（已知坏），HK 的角度证据用连续角度 MAE / dp_bin。
-5. 各脚本对 server 的并发提速无效（server 是 batch=1 串行生成）；要提速就多起 server 实例分流。
+The external LLM judge is intentionally excluded from the local deterministic
+queue. Use `pipelines/l2/llm_judge/README.md` with explicit rows, beliefs, and
+skill-library paths. Judge outputs remain review-isolated until accepted by the
+maintainer.

docs/VERIFICATION.md

@@ -1,90 +0,0 @@
-# 跑通验证（2026-07-13）
-
-迁移到 `pactbench/` 之后，**逐条真跑**每个入口。结论：**全部可跑，且数字逐位复现 canonical**。
-过程中修掉 6 个 bug —— 其中 3 个是迁移引入的，**3 个是原本就存在、会产出错误数字的老 bug**。
-
-## 验证矩阵
-
-| 入口 | V Rising | Hollow Knight | Isaac | 说明 |
-|---|---|---|---|---|
-| `data/audit_dataset.sh` | ✅ 跑通 | ✅ 跑通 | ✅ 跑通 | |
-| `data/build_metadata.py` | —（无，见 vrising README） | ✅ 跑通 | ✅ 跑通 | |
-| `data/build_manifest.sh` | ✅ 跑通 | ✅ 跑通 | ✅ 跑通 | |
-| `l1/eval_official_from_ckpt.sh` | ⛔ RGB cache 已被清 | ✅ **完全复现** | ✅ **完全复现**（修 bug 后） | |
-| `l1/train_l1.sh` | —（无） | ✅ 守卫正常 | ✅ 守卫正常 | 未真训（重活），守卫按预期拦截 |
-| `l1/run_foundation_baselines.sh` | ✅ 跑通 | ❌ 未做 | ❌ 未做 | |
-| `l1/run_latency_b8.sh` | ✅ 跑通 | — | — | |
-| `l1/build_eval_status.sh` | ✅ 跑通 | — | — | |
-| `l2/run_semantic_views.sh` | ✅ **完全复现** | ✅ **完全复现** | ✅ **完全复现** | gemma server 在线 |
-| `pipelines/l2/run_image_modality_ablation.sh` | （vrising 已有产物） | ❌ 未做 | ❌ 未做 | |
-| `pipelines/l2/llm_judge/*` | ⏸ 暂缓 | ⏸ 暂缓 | ⏸ 暂缓 | 口径未定，依赖外部 API |
-
-**「完全复现」= 重跑产出的指标和 `results/` 里 canonical 的数字逐位一致**（L1 比对 8 个字段，L2 比对
-`sample_set_id` / follow / flip / name_bias / n）。
-
-唯一跑不了的是 **V Rising 的 L1 评测**：RGB cache 在磁盘写满时被清了，shell 会干净地报错退出（exit=2）。
-重建：`python3 pact/build_rgb_frame_cache.py --workers 32`（约 2–3 分钟，需 ~30G 磁盘，当前只剩 238G，注意）。
-
-## 修掉的 bug
-
-### 老 bug（原本就在，会产出错误数字）
-
-**① Isaac 的 L1 评测 shell 默认加载的是「已废弃的坏 ckpt」。**
-`eval_official_from_ckpt_isaac.sh` 的 `CKPT` 默认指向 `raw_rgb_..._train30k_...pt` ——
-正是量纲坏掉那个（预测被截断在 45）。已改为 `ckpt/isaac/l1_main_fixed_e10.pt`。
-
-**② Isaac 的 L1 评测没传 `--distance_norm 1000`，而训练时传了。** 评测与训练量纲不一致 →
-指标全错（`distance_bin` 0.33 vs 真实 0.89）。已把 `--distance_norm/--distance_clamp` 加进评测 shell。
-修完重跑，**8 个字段全部逐位复现 canonical**。
-
-**③ V Rising / HK 的 L2 shell 默认写进「v1 采样」的旧目录。**
-采样器代码已经修成 v2（按 `(boss, fight, dp_bin)` 分层），但 shell 的默认 tag 仍指向 v1 的 run 目录。
-照默认跑 + `--resume` → **v2 的新状态混进 v1 的旧 rows**，产出坏数字。
-（v1 确实高估：HK v1 follow 92.5% vs v2 89.8%。）
-已把默认 tag 改成 v2：`VRISING_RUN_TAG=samplev2`、`HK_RUN_TAG=test10_samplev2`。
-
-**④ Isaac 的训练 shell `CKPT_OUT` 默认指向「废弃坏 ckpt」的路径。**
-该路径现在是回链，重训会顺着链把 bug 证据文件覆盖掉。已改为 `ckpt/isaac/l1_main_fixed_e10.pt`。
-HK 的训练 shell 默认 cache/ckpt 名也和 canonical 对不上（canonical 训练入口其实是
-`games/hk/l1/run_train30k_pipeline.sh`）——默认值已对齐。
-
-### 迁移引入的 bug（已修）
-
-**⑤ `games/{hk,isaac}/data/build_metadata.py` 还按旧 `scripts/` 路径 import。** → 改指 `pact/`。
-
-**⑥ 三个 py 里的默认路径常量仍指向旧布局**：
-`eval_l2_skill_description_intervention.py`（`schemas/skill_library.json`）、
-`eval_l2_gemma4_img_ablation.py`（`ROOT = parents[4]`，在旧的深 4 层位置才对）、
-`l2_gemma_decide.py`（硬编码绝对路径）。已全部改为新布局。
-另外 V Rising 的 L2 shell 现在像 HK/Isaac 一样**显式传 `--beliefs/--skill_library`**，不再依赖默认常量。
-
-## 怎么复验
-
-```bash
-source env.sh
-bash games/{game}/data/audit_dataset.sh                 # 秒级
-bash games/{game}/l2/run_semantic_views.sh              # 需 gemma server；--resume 下不重调 LLM，只重算指标
-CUDA_VISIBLE_DEVICES=<idle> bash games/{game}/l1/eval_official_from_ckpt.sh   # HK/Isaac 可跑；vrising 需先重建 cache
-```
-
----
-
-## L1 补做（HK/Isaac）+ 过夜整理（2026-07-13 续）
-
-给 HK/Isaac 补齐 L1 三块（视觉基线 / 无图先验 / belief 字段筛选），过程中修的 bug：
-
-**① `eval_l1_foundation_baselines.py` 对 Isaac 像素量纲 probe 塌缩。**
-距离回归 loss 硬编码 `× 30.0`（引擎量纲还原），Isaac dp 是像素（中位数 147），×30=4410 → smooth_l1 loss 爆炸主导总 loss → 分类头没学、塌缩到多数类（dp_bin 0.335=多数类频率，两个 backbone 数字完全相同）。
-已加 `--distance_norm`（默认 30）+ `--distance_clamp`，改 4 处硬编码 30。Isaac 用 `--distance_norm 1000` 重训后救回（dp_bin dinov2 0.335→0.511、videomae→0.399，两 backbone 区分开）。
-
-**② `eval_l1_foundation_baselines.py` 的 `train_probe` 阈值 KeyError。**
-`--max_train_samples 10000` 按顺序截断，漏掉 fight 靠后的 boss（HK HiveKnight、Isaac DukeOfFlies），eval 时该 boss 查不到距离阈值崩溃。已加全局阈值兜底。
-
-**③ `eval_l2_belief_policy.py` 对 Isaac 4858 场 fight 的 IO 爆炸。**
-`collect_decision_samples` 逐 fight 读 jsonl，Isaac train 4858 场读两遍失控。已加 `--max_train_fights`（Isaac 用 400），线性 probe 不需要几千场。
-
-**④ 标签硬编码。** `eval_l1_no_image_no_engine_prior.py` + `build_l1_img_ablation_summary.py` 的 train/test_set_id 和输出文件名写死成 V Rising 的 8075/18068。已参数化，从数据继承。
-
-**⑤ 环境变量污染坑。** 当前 shell 有预设的 `GROUPS=1000` 环境变量，会覆盖 `${GROUPS:-default}`。belief probe shell 已改用硬编码数组 `PROBE_GROUPS=(...)` 绕开；启动脚本用 `env -u GROUPS`。
-
-**验证**：`registry/build_registry.py` 逐条核验通过；`registry/status.py` 显示三游戏除「L2 决策质量评价」外全部完成。所有结果已进 `组会6_三游戏汇总.pptx`（29 页，新增 p22-29）。

docs/exp.md

@@ -1,367 +0,0 @@
-# PACT L1/L2 Evaluation Protocol
-
-Version: `pact-eval-v1`
-Effective date: 2026-07-09
-
-This file defines the default setting for current and future L1/L2 experiments.
-It is not a result summary. A result is comparable only if it uses the same
-setting id, split, sample set, input modality, and metric scope defined here.
-
-## Core Rule
-
-Every experiment must declare:
-
-- `protocol`: `pact-eval-v1`
-- `layer`: `L1` or `L2`
-- `setting_id`
-- `train_set_id`
-- `test_set_id` or `sample_set_id`
-- `input_modality`
-- `model_id`
-- `seed`
-- `metric_scope`: `full_set`, `confidence_filtered`, or `diagnostic`
-
-If any of these change, the run is a different experiment and must not be put
-in the same comparison row without an explicit ablation label.
-
-## Canonical Data Settings
-
-### TRAIN-COVERED-18068
-
-Default training set for L1 visual models and visual baselines.
-
-- Manifest: `out/layered/manifest_latent_covered.json`
-- Split: `train`
-- Rows: `18,068`
-- Sampling unit: decision row
-- Row identity: `boss`, `fight`, `time` when filtering cached features;
-  `boss`, `fight`, `index` when using handoff JSONL rows
-
-All future L1 visual comparisons should train on this set unless the experiment
-is explicitly a data-size or split ablation.
-
-### TEST-OFFICIAL-8075
-
-Default test set for L1 and source pool for L2.
-
-- Manifest: `out/layered/manifest.json`
-- Split: `test`
-- Rows: `8,075`
-- Input video format for L1 visual models:
-  - RGB history frames
-  - offsets `[-8, -4, -2, -1, 0]`
-  - shape `5 x 3 x 192 x 336`
-- Default metric scope: full set, no confidence filtering
-
-All future L1 headline tables and default L1 ablations should use this test set.
-
-### L2-SAMPLE-200-v1
-
-Default fixed L2 sample for API-costly L2 experiments.
-
-- Source pool: `TEST-OFFICIAL-8075` handoff rows
-- Frozen row file:
-  `out/layered/l2_skill_desc_intervention_gemma_anon_n200_rows.jsonl`
-- Rows: `200`
-- Original selection strategy: deterministic stratified round-robin over
-  `boss x dp_bin`, taking rows in source order
-- Boss counts in the frozen sample:
-  - MilitiaLeader: `68`
-  - StoneBreaker: `68`
-  - ToadKing: `64`
-
-Future L2 method comparisons, description interventions, image-input
-diagnostics, and LLM-judge runs should use this same row set by default. If a
-new L2 sample is needed, create a new sample id such as `L2-SAMPLE-500-v1` and
-store the row list before running models.
-
-### TEST-COVERED-6013-LEGACY
-
-Legacy diagnostic set used by earlier L1 image-input ablation.
-
-- Rows: `6,013`
-- Existing use: old `+img` vs strict `-img` distance-bin diagnostic
-- Status: allowed for reproducing old numbers only
-- Not allowed for new headline L1/L2 comparisons
-
-Future experiments should not mix `TEST-COVERED-6013-LEGACY` with
-`TEST-OFFICIAL-8075` in the same table.
-
-## L1 Protocols
-
-### L1-MAIN-VISUAL
-
-Purpose: compare visual situation-understanding models.
-
-- `train_set_id`: `TRAIN-COVERED-18068`
-- `test_set_id`: `TEST-OFFICIAL-8075`
-- `metric_scope`: `full_set`
-- Input modality: RGB history
-- Required methods:
-  - PACT-L1
-  - DINOv2-S + MLP
-  - VideoMAE-B + MLP
-- Required metrics:
-  - `dp_bin_accuracy`: accuracy of the predicted player-distance bin
-  - `angle_bin_accuracy`: accuracy of the predicted player-angle bin
-
-Optional diagnostics, not headline metrics:
-
-  - continuous distance MAE / dp@2
-  - front-cone F1
-  - decision-zone / tactical-sector accuracy
-  - latency ms
-
-DINOv2-S + MLP and VideoMAE-B + MLP are image-based frozen-backbone baselines.
-They are not no-image baselines.
-
-The main table must not filter rows by `distance_confidence >= 0.9`. If a
-high-confidence analysis is reported, it must be a separate diagnostic table
-with coverage reported for every method.
-
-### L1-IMG-ABLATION
-
-Purpose: test whether L1 geometry depends on image input.
-
-Default future setting:
-
-- `train_set_id`: `TRAIN-COVERED-18068`
-- `test_set_id`: `TEST-OFFICIAL-8075`
-- Paired conditions:
-  - `+img`: model receives RGB history
-  - `-img_strict`: model receives no RGB and no current engine truth
-- `metric_scope`: `full_set`
-
-Strict `-img` must not read:
-
-- RGB frames
-- `raw_obs`
-- `dp`
-- `da`
-- `rel_angle`
-- current HP
-- current cooldowns
-- current previous skill
-- current row boss/fight/index metadata at inference time
-
-Allowed strict `-img` information:
-
-- training-set priors fixed before evaluation
-- constants encoded in the experiment config
-
-If a no-image method uses history, tracker state, previous predictions, or boss
-identity, it is not `-img_strict`. Give it a different condition name, such as
-`-img_history` or `-img_boss_prior`.
-
-Required output metrics:
-
-- `dp_bin_accuracy`
-- `angle_bin_accuracy`
-
-Auxiliary metrics should still be emitted for completeness when available, but
-must be marked as auxiliary and must not drive the L1 headline claim:
-
-- continuous distance / angle diagnostics
-- front-cone, decision-zone, tactical-sector, behind diagnostics
-- tracker/state diagnostics such as HP phase
-- runtime latency
-
-### L1-CONFIDENCE-DIAGNOSTIC
-
-Purpose: measure reliability of high-confidence predictions.
-
-This is diagnostic, not the main accuracy metric.
-
-Rules:
-
-- Must state threshold, e.g. `distance_confidence >= 0.9`
-- Must report coverage
-- Must report the full-set metric beside the filtered metric
-- Must not be compared against another method's full-set metric
-- If comparing multiple methods, apply the same confidence rule to all methods
-  and report coverage for all methods
-
-For L1 multiclass heads, confidence is the max softmax probability of the
-predicted class. For binary heads, confidence is `max(p, 1-p)` after sigmoid.
-
-## L2 Protocols
-
-### L2 Input Views
-
-Every L2 run must declare `belief_view`.
-
-#### `belief_view=full`
-
-Purpose: test L2 with the current full L1 handoff prompt.
-
-Allowed L1 input fields:
-
-- tracker/state fields: previous skill, skill phase, skill finished, HP phase,
-  cooldown/menu information
-- distance fields: `dp`, `dp_bin`, distance text
-- angle/front fields: angle value/bin, `front_cone`
-- derived geometry fields: `decision_zone`, `tactical_sector`, `behind`
-
-This is the "as-currently-used" version and may expose overcomplete L1 fields.
-
-#### `belief_view=compact`
-
-Purpose: test the paper Fig. 1 compact interface.
-
-Allowed L1 input fields:
-
-- tracker/state fields: previous skill, skill phase, skill finished, HP phase,
-  cooldown/menu information
-- `dp`
-- `dp_bin`
-- `front_cone`
-
-Forbidden L1 input fields:
-
-- angle value/bin
-- `angle_36bin`
-- `decision_zone`
-- `tactical_sector`
-- `behind`
-- any other L1 geometry not listed above
-
-This is the preferred paper-facing L2 interface unless the experiment is
-explicitly a full-vs-compact ablation.
-
-### L2-SEMANTIC-INTERVENTION
-
-Purpose: test whether L2 decisions follow skill mechanics descriptions rather
-than skill names, formatting, or priors.
-
-- `sample_set_id`: `L2-SAMPLE-200-v1`
-- Source belief: L1 handoff from `TEST-OFFICIAL-8075`
-- Required input versions:
-  - `belief_view=full`
-  - `belief_view=compact`
-- Default model temperature: `0`
-- Required variants:
-  - `full`: full skill descriptions
-  - `no_desc`: skill descriptions removed
-  - `swap_desc`: skill mechanics descriptions swapped across skills
-- Required metrics:
-  - `no_desc_decision_change_rate`
-  - `swap_desc_decision_change_rate`
-
-Parsing validity is a sanity check, not a headline metric.
-
-### L2-IMG-DIAGNOSTIC
-
-Purpose: test whether adding current RGB image content changes L2 decisions.
-
-- `sample_set_id`: `L2-SAMPLE-200-v1`
-- Paired conditions:
-  - `text_only`: L1 belief + skill menu/descriptions
-  - `text_plus_img`: same text payload plus current RGB frame
-- Required metric:
-  - skill changed rate
-- Optional diagnostics:
-  - family match rate
-  - macro recall to target skill
-  - prediction entropy
-
-This diagnostic does not by itself prove decision quality.
-
-This is not part of the current L2 headline metric set. Do not include it in
-the main L2 table unless explicitly labeled as an image-input diagnostic.
-
-### L2-LLM-JUDGE
-
-Purpose: judge whether the selected L2 skill is tactically acceptable when
-exact next-skill labels are not unique.
-
-- `sample_set_id`: `L2-SAMPLE-200-v1`
-- Required input versions:
-  - `belief_view=full`
-  - `belief_view=compact`
-- Judge input:
-  - L1 fields permitted by the run's declared `belief_view`
-  - legal skill options
-  - skill mechanics descriptions
-  - selected skill
-- Judge must not see:
-  - hidden engine next-skill label as the answer
-  - model name of the policy being judged
-- Required outputs:
-  - selected score `1..5`
-  - selected acceptable boolean
-  - acceptable option set
-  - top option set
-  - short reason
-- Required comparisons:
-  - `llm_judge_selected_acceptable_rate`
-  - random-choice expectation under the same acceptable/top sets
-
-L2 confidence is the LLM's self-reported JSON confidence. It is not comparable
-to L1 softmax confidence.
-
-## Run Storage
-
-Every official run must create a directory:
-
-```text
-out/eval_runs/{run_id}/
-```
-
-where:
-
-```text
-run_id = {date}_{layer}_{setting_id}_{model_id}_{condition}_{seed}
-```
-
-Required files:
-
-- `run_config.json`: all protocol fields and command-line args
-- `metrics.json`: machine-readable metrics
-- `rows.jsonl` or `predictions.jsonl`: row-level outputs when applicable
-- `README.md`: one-paragraph description of what changed
-- `DEVIATION.md`: required only if the run differs from this protocol
-
-Never overwrite an existing official run directory. Create a new run id.
-
-## Reporting Rules
-
-A slide, table, or paper sentence must include:
-
-- setting id
-- train set id
-- test/sample set id
-- sample count
-- metric scope
-- whether image input is used
-
-Allowed concise examples:
-
-- `L1-MAIN-VISUAL on TEST-OFFICIAL-8075, full-set metrics`
-- `L1-IMG-ABLATION on TEST-OFFICIAL-8075, +img vs -img_strict`
-- `L2-SEMANTIC-INTERVENTION on L2-SAMPLE-200-v1`
-- `L1-CONFIDENCE-DIAGNOSTIC, distance_confidence >= 0.9, coverage reported`
-
-Forbidden comparisons:
-
-- DINOv2/VideoMAE full-set metrics vs PACT-L1 confidence-filtered metrics
-- `TEST-COVERED-6013-LEGACY` numbers in the same table as
-  `TEST-OFFICIAL-8075` numbers
-- DINOv2/VideoMAE described as no-image baselines
-- L2 parsing validity reported as decision performance
-
-## Changing The Protocol
-
-Changing any of the following requires a new protocol version or a new setting
-id:
-
-- train manifest
-- test manifest
-- L2 sample row list
-- RGB history offsets or image resolution
-- allowed inputs for no-image conditions
-- model temperature for L2 methods
-- confidence threshold used for diagnostic filtering
-- metric definition
-
-Protocol changes must be made before running the experiment, not after seeing
-the result.

docs/hk_experiment_checklist.md

@@ -1,105 +0,0 @@
-# HK 实验清单（Hollow Knight）
-
-> 目标：把 HK 从「数据就绪」一路跑到 L2 语义干预，与 V Rising 主线对齐。
-> 每完成一项就把 `[ ]` 改成 `[x]` 并在「产物 / 结果」列填实际数字或路径。
-> 最后更新：2026-07-10（B 完成，D 待跑）
-
-游戏独立原则：HK 单独训练 L1、单独评测 L2，用 HK 自己的技能机制，不共享多游戏模型。
-协议对齐 V Rising：训练/测试同一套 fight 级切分；L2 用 200 个分层采样状态、匿名技能 ID、Gemma-4-E2B-it、温度 0、三种描述条件（full / no_desc / swap_desc）。
-
----
-
-## A. 数据侧（已完成）
-
-- [x] **A1 数据审计** — `code/hk/data/audit_dataset.sh`　产物：`out/eval_runs/hk_dataset_audit.json`
-- [x] **A2 ontology + 技能库** — `code/hk/data/build_metadata.py`　产物：`out/hk/ontology.json`, `schemas/hk_skill_library.json`
-- [x] **A3 fight 级切分 manifest** — `code/hk/data/build_manifest.sh`　产物：`out/hk/layered/manifest.json`
-- [x] **A4 RGB cache（train 30k + official test）** — `scripts/build_rgb_frame_cache.py`
-      产物：`raw_rgb_train30k_current0_h192w336.pt`(29G, 30000/30000 零缺失), `raw_rgb_test_official_current0_h192w336.pt`(2.2G)
-
-## B. L1 训练与评测
-
-- [x] **B1 L1 训练** — ✅ 完成（2026-07-10，10 epoch，GPU2，15:56 落盘；改用 `code/hk/l1/train_l1.sh` 直跑）
-      log：`out/hk/logs/20260710_hk_l1_train_direct_gpu2.log`
-      产物：`out/hk/situation/raw_rgb_resnet18_decision_train30k_from_dp_current0_e10.pt`(ckpt 52MB)
-            + `..._official_test.json`(metrics) + `beliefs_..._official_test.jsonl`(2242 行)
-- [x] **B2 L1 官方测试性能指标** — ✅ 完成（训练自带在 official test 上评测；n=2242）
-      产物：`out/hk/situation/raw_rgb_resnet18_decision_train30k_from_dp_current0_e10_official_test.json`
-      指标在 json 的 `continuous` / `fields` 键下（顶层 `metrics` 为空）：
-      | 指标 | HK | V Rising 对照 |
-      |---|---|---|
-      | Dist. MAE ↓ | **0.516** | 0.2621 |
-      | dp@2（dp_within_2）↑ | **0.9648** | 0.9962 |
-      | dp@4 ↑ | **0.9982** | — |
-      | Angle MAE ↓ | **3.65°** | 11.73° |
-      | Angle@20° ↑ | **0.9723** | 0.8295 |
-      | Angle@10° ↑ | **0.9277** | — |
-      | Range-bin acc.（player_distance_bin）↑ | **0.7021** | 0.8966 |
-      | hp_phase acc. ↑ | 0.2988 | — |
-      结论：HK L1 几何其实相当好——距离/角度连续预测接近甚至优于 V Rising（angle@20° 0.97 vs 0.83）。
-      ⚠️ 但 `player_angle_bin` 分类头 accuracy=0.0（连续角度好、离散 bin 头坏，bin 定义可能与 HK 不匹配）；
-      Front-cone F1 / Zone Acc. / Tactical-sector 在 HK 这次 eval 输出里未计算（不在 json 内）。
-
-## C. L1 → L2 桥接
-
-- [x] **C1 桥接 → L2 输入** — ✅ 不需单独 handoff：L2 脚本 `nested_belief()` 直接消费 flat beliefs
-      beliefs jsonl 的 `belief` 字段含全部所需 flat 字段（player_distance_value/bin、front_cone、
-      decision_zone、tactical_sector、cooldown_ready/seconds、prev_boss_skill、hp_phase…）。
-      跑 L2 时把 `HK_L1_HANDOFF` 指向该 beliefs 文件即可（早前指向不存在的 handoff 路径→被 block）。
-
-## D. L2 语义干预（核心结果）
-
-- [x] **D1 L2 full view** — ✅ 完成（2026-07-11 03:15 落盘，200 行，已核实 md5/wc）
-      产物：`out/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_full_full-no_desc-swap_seed0/metrics.json`(+rows.jsonl 200 行)
-      结果：Desc-follow=**62.4%** / Neither=33.5% / Name-bias=**2.0%** / No-desc change=87.0% / Swap change=98.0% / valid=98.5%
-- [x] **D2 L2 compact view（Fig.1 接口）** — ✅ 完成（2026-07-11 03:54 落盘，200 行，已核实）
-      产物：`out/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_compact_full-no_desc-swap_seed0/metrics.json`
-      结果：Desc-follow=**95.0%** / Neither=1.0% / Name-bias=**2.0%** / No-desc change=92.4% / Swap change=98.0% / valid=99.0%
-- [x] **D3 汇总对比表** — compact vs full，随机 follow 基线≈29.2%（1/K̄, K̄=3.42）
-      结论：✅ 复现。compact≫full（95.0% vs 62.4%）、name-bias 仅 2%，
-      compact=3.25×基线、full=2.1×基线。决策受机制语义强控制，且 compact≥full 与 V Rising 一致。
-
-## 可选 / 视时间补（对齐 V Rising 但非主线）
-
-- [ ] **E1 L1 图像消融** — PACT-L1 有图 vs 严格无图先验（对应 V Rising 第 5 页）
-- [ ] **E2 L1 belief→policy probe** — compact vs overcomplete 的 masked MLP probe（对应 V Rising 第 8 页）
-- [ ] **E3 L2 boss 级分解** — D 的按 boss（FalseKnight / HiveKnight / Hornet …）拆解
-
----
-
-## 依赖链（一眼看清能不能并行）
-
-```
-A(✓) ── B1(训练,等GPU) ── B2(L1评测) ─┐
-                        └─ C1(handoff) ── D1(L2 full) ─┐
-                                        └─ D2(L2 compact) ── D3(汇总)
-```
-B2 与 C1 都只依赖 B1，可并行。D1/D2 依赖 C1 + gemma server，可并行（两张卡）。
-
-## 阻塞记录
-
-- 2026-07-10 15:41：B1 一直在轮询「GPU2 busy: memory.used=11059 MiB」——被 L2 模型消融的 gemma server 占用。
-- 2026-07-10 15:44：关掉 4 个 gemma server（含一个漏网的 617434），GPU2 释放到 3 MiB。
-- 2026-07-10 15:50：`run_train30k_pipeline.sh` 的 build_cache 子进程（PID 3880228）卡死——抽帧早已 30000/30000 完成，却卡在 torch.save 之前空转（163% CPU、48.9G RSS、零写入），挡住整个 pipeline。
-- 2026-07-10 15:52：验证两个 cache 完整可加载，终止卡死 pipeline，改用 `train_l1.sh` 直接训练（cache 已在，自动跳过重建）。
-- 2026-07-10 15:56：训练正常完成 10 epoch，产物落盘（ckpt 52MB、beliefs 2242 行、metrics json）。
-- 2026-07-10（复盘）：高负载期 shell 曾返回虚假输出，一度误报 handoff/L2 已完成——经独立核实 `out/hk/eval_runs` 不存在、
-  handoff 文件不存在、L2 run log 显示每次都被 block。已据实修正本清单；L2 实际需先起 gemma server 再跑。
-
----
-
-## HK L2 结果小结（D3）— 待 D1/D2 跑完后填入真实数字
-
-协议：n=200 分层采样，匿名技能 ID，Gemma-4-E2B-it，温度 0，三条件 full/no_desc/swap_desc。
-指标：Desc-follow=跟随被交换机制文本的比例（好）；Neither=既不跟随也不守身份，漂到无关技能（噪声）；Name-bias=守住原技能身份（坏）。三者互斥且合计=Swap-change；随机基线 follow≈1/K̄。
-
-| Belief view | No-desc change | Swap-change | Desc-follow ↑ | Neither ↓ | Name-bias ↓ | valid |
-|---|---|---|---|---|---|---|
-| full    | 87.0% | 98.0% | 62.4% | 33.5% | 2.0% | 98.5% |
-| compact | 92.4% | 98.0% | **95.0%** | 1.0% | 2.0% | 99.0% |
-
-随机 follow 基线≈29.2%（K̄=3.42）→ compact=3.25×、full=2.1×。
-按 boss（compact / full 的 desc-follow）：FalseKnight 95.6% / 82.4%，HiveKnight 97.0% / 72.7%，Hornet 92.2% / 30.2%。
-（full 下 Hornet 是唯一难点 30%，compact 补齐到 92%——belief 视图收窄反而让语义控制更稳。）
-
-## 状态：A/B/C/D 全部完成 ✅（含 L1 单帧消融）　（可选项 E1/E2/E3 未做）

docs/hk_experiment_plan.md

@@ -1,238 +0,0 @@
-# Hollow Knight Experiment Plan
-
-Last updated: 2026-07-09 08:12:54 UTC
-
-Scope: HK only. Do not modify V Rising or Isaac outputs.
-
-## Current Executable State
-
-| Area | Status | Evidence / Path |
-|---|---|---|
-| Processed data | Ready | `data/hk/processed -> data/_hf_teawhite_vrising_hk_isaac/HK` |
-| Data audit | Passed | `out/eval_runs/hk_dataset_audit.json`, `warnings=[]`, entities: FalseKnight, HiveKnight, Hornet |
-| Ontology | Ready, data-derived | `out/hk/ontology.json` from policy actions and render prompts |
-| Skill library | Ready, conservative | `schemas/hk_skill_library.json`; mechanics are render-prompt-derived and not human validated |
-| Split manifest | Ready | `out/hk/layered/manifest.json` |
-| L1 RGB cache smoke | Passed | `out/hk/situation/smoke/raw_rgb_test_current0_smoke24.pt`, kept=24, missing=0 |
-| L1 training/eval | Running fast train30k path | Full HK train cache is too slow/heavy for the first run; `code/hk/l1/train_l1.sh` now accepts cache/result path overrides |
-| L1 ablation/baselines | Blocked | Needs HK L1 result JSON before no-image prior and image ablation summary can run |
-| L2 semantic intervention | Blocked for formal run | Needs HK L1 handoff rows; `code/hk/l2/run_semantic_views.sh` is a guarded entry point |
-| LLM judge | Deferred | Same policy as V Rising current plan |
-
-## Data And Split
-
-Split policy is shared with V Rising: sorted fights, last 3 test, preceding 3 validation.
-
-| Boss | All | Train | Val | Test | Skills |
-|---|---:|---:|---|---|---:|
-| FalseKnight | 226 | 220 | 221,222,223 | 224,225,226 | 6 |
-| HiveKnight | 77 | 71 | 72,73,74 | 75,76,77 | 6 |
-| Hornet | 220 | 214 | 215,216,217 | 218,219,220 | 7 |
-
-Important caveat: FalseKnight `opened` is a high-frequency policy action/state.
-The shared manifest logic treats it as a skill because it is not `idle`,
-`turn`, `death`, or `move_*`. Do not filter it without a documented protocol
-decision.
-
-## Commands Completed
-
-```bash
-python code/hk/data/build_metadata.py
-bash code/hk/data/build_manifest.sh
-bash code/hk/data/audit_dataset.sh
-python -m py_compile code/hk/data/build_metadata.py
-python scripts/build_rgb_frame_cache.py \
-  --manifest out/hk/layered/manifest.json \
-  --processed_root data/hk/processed \
-  --split test \
-  --history_offsets="-8,-4,-2,-1,0" \
-  --frame_in_cell 2 \
-  --height 192 \
-  --width 336 \
-  --allow_current_frame \
-  --max_samples 24 \
-  --out out/hk/situation/smoke/raw_rgb_test_current0_smoke24.pt
-bash -n code/hk/l1/train_l1.sh
-bash -n code/hk/l2/run_semantic_views.sh
-bash code/hk/l1/train_l1.sh
-bash code/hk/l2/run_semantic_views.sh
-```
-
-Validation also checked that ontology, skill library, and manifest cover the
-same HK bosses/skills and that train/val/test splits do not overlap.
-
-## Required Experiment Blocks
-
-### B0: Data Audit And Shared Split
-
-- Claim tested: HK can use the same fight-level split protocol as V Rising.
-- Dataset / split: `out/hk/layered/manifest.json`.
-- Metrics: audit warnings, missing video/render files, row/obs field coverage,
-  split disjointness.
-- Status: complete.
-
-### B1: PACT-L1 Main HK Result
-
-- Claim tested: PACT-L1 can predict HK L1 belief fields from RGB under the same
-  protocol.
-- Dataset / split: HK manifest train vs official test split.
-- Compared systems: PACT-L1 RGB model, strict no-image global prior, foundation
-  feature probes if HK feature caches are built.
-- Metrics: field accuracy, macro/balanced metrics where available, confidence /
-  ECE, and overall output summary from the L1 result JSON.
-- Status: approved fast run uses a 30,000-sample train cache and the unchanged
-  official test cache. Report as `HK-L1 train30k`; do not treat it as the final
-  full-data HK result.
-
-Train split size audit:
-
-| Split | Samples |
-|---|---:|
-| Train full | 144,418 |
-| Train fast cache | 30,000 |
-| Val | 2,614 |
-| Test official | 2,242 |
-
-The current cache builder's `max_samples` path uses boss-balanced prefix
-sampling, so the fast run is useful for pipeline validation and early results
-but may under-cover later train fights and long-tail skills.
-
-Prepared cache commands:
-
-```bash
-python scripts/build_rgb_frame_cache.py \
-  --manifest out/hk/layered/manifest.json \
-  --processed_root data/hk/processed \
-  --split train \
-  --history_offsets="-8,-4,-2,-1,0" \
-  --frame_in_cell 2 \
-  --height 192 \
-  --width 336 \
-  --allow_current_frame \
-  --max_samples 30000 \
-  --out out/hk/situation/raw_rgb_train30k_current0_h192w336.pt
-
-python scripts/build_rgb_frame_cache.py \
-  --manifest out/hk/layered/manifest.json \
-  --processed_root data/hk/processed \
-  --split train \
-  --history_offsets="-8,-4,-2,-1,0" \
-  --frame_in_cell 2 \
-  --height 192 \
-  --width 336 \
-  --allow_current_frame \
-  --out out/hk/situation/raw_rgb_train_full_current0_h192w336.pt
-
-python scripts/build_rgb_frame_cache.py \
-  --manifest out/hk/layered/manifest.json \
-  --processed_root data/hk/processed \
-  --split test \
-  --history_offsets="-8,-4,-2,-1,0" \
-  --frame_in_cell 2 \
-  --height 192 \
-  --width 336 \
-  --allow_current_frame \
-  --out out/hk/situation/raw_rgb_test_official_current0_h192w336.pt
-```
-
-Prepared heavy training command, only after an idle GPU is confirmed:
-
-```bash
-TRAIN_CACHE=out/hk/situation/raw_rgb_train30k_current0_h192w336.pt \
-TEST_CACHE=out/hk/situation/raw_rgb_test_official_current0_h192w336.pt \
-OUT_JSON=out/hk/situation/raw_rgb_resnet18_decision_train30k_from_dp_current0_e10_official_test.json \
-BELIEF_OUT=out/hk/situation/beliefs_raw_rgb_resnet18_decision_train30k_from_dp_current0_e10_official_test.jsonl \
-CKPT_OUT=out/hk/situation/raw_rgb_resnet18_decision_train30k_from_dp_current0_e10.pt \
-CUDA_VISIBLE_DEVICES=<idle_gpu> \
-HK_ALLOW_HEAVY_TRAINING=1 \
-bash code/hk/l1/train_l1.sh
-```
-
-Equivalent guarded pipeline entry point:
-
-```bash
-GPU_ID=<idle_gpu> bash code/hk/l1/run_train30k_pipeline.sh
-```
-
-### B2: PACT-L1 Ablations And Baselines
-
-- Claim tested: HK L1 gains are not explained by global priors or foundation
-  features alone.
-- Must-run after B1: strict no-image prior from HK L1 JSON, image ablation table,
-  foundation baselines if HK feature caches exist.
-- Status: blocked on B1 output.
-
-Prepared strict-prior command:
-
-```bash
-python evaluation/ablations/pact_eval_v1_20260709/scripts/eval_l1_no_image_no_engine_prior.py \
-  --source out/hk/situation/raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.json \
-  --out out/hk/ablations/l1_no_image_no_engine_prior_official_test.json \
-  --test_set_id HK-TEST-OFFICIAL
-```
-
-### B3: L2 Semantic Intervention
-
-- Claim tested: HK L2 decisions change when skill descriptions are removed or
-  swapped, for both full and compact L1 handoff views.
-- Inputs: real HK L1 handoff rows, not oracle policy rows.
-- Metrics: no-desc decision change rate, swap-desc decision change rate,
-  desc-follow, name-bias. LLM judge remains deferred.
-- Status: blocked on B1 handoff rows.
-
-Prepared commands after HK L1 handoff exists:
-
-```bash
-GEMMA_OPENAI_BASE_URL=http://127.0.0.1:8018/v1 \
-GEMMA_MODEL=gemma-4-E2B-it \
-GEMMA_TEMPERATURE=0 \
-python scripts/eval_l2_skill_description_intervention.py \
-  --beliefs out/hk/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl \
-  --skill_library schemas/hk_skill_library.json \
-  --backend gemma \
-  --limit 200 \
-  --sample_strategy stratified \
-  --anonymous_names \
-  --belief_view full \
-  --resume \
-  --out out/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_full_full-no_desc-swap_seed0/metrics.json \
-  --rows_out out/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_full_full-no_desc-swap_seed0/rows.jsonl
-
-GEMMA_OPENAI_BASE_URL=http://127.0.0.1:8018/v1 \
-GEMMA_MODEL=gemma-4-E2B-it \
-GEMMA_TEMPERATURE=0 \
-python scripts/eval_l2_skill_description_intervention.py \
-  --beliefs out/hk/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl \
-  --skill_library schemas/hk_skill_library.json \
-  --backend gemma \
-  --limit 200 \
-  --sample_strategy stratified \
-  --anonymous_names \
-  --belief_view compact \
-  --resume \
-  --out out/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_compact_full-no_desc-swap_seed0/metrics.json \
-  --rows_out out/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_compact_full-no_desc-swap_seed0/rows.jsonl
-```
-
-## Stop / Go Gates
-
-| Gate | Go Condition | Stop Condition |
-|---|---|---|
-| G0 metadata | Manifest builds and audit warnings stay zero | Missing render/video/policy rows or schema mismatch |
-| G1 cache | Train/test RGB caches build with missing=0 or documented tiny drop | Video decode failures or unexpected sample loss |
-| G2 training | `nvidia-smi` shows an idle GPU with memory.used < 500 MiB | No idle GPU or another process owns the GPU |
-| G3 L2 | HK L1 handoff rows exist and use `schemas/hk_skill_library.json` | Only oracle rows exist, or semantic fields are judged too weak |
-
-## Open Risks
-
-- HK skill library is conservative and render-prompt-derived. It is usable for
-  manifest construction and prompt wiring, but formal L2 conclusions should
-  note that the descriptions are not human validated.
-- `export_l1_handoff_payloads.py` defaults include V Rising paths and a
-  V Rising-derived affordance matrix. HK commands must pass HK paths explicitly,
-  and the tactical prior should be neutralized or replaced before paper-grade
-  HK L2 analysis if that field is used.
-- HK L1/L2 shell wrappers are guarded entry points. L1 refuses to train unless
-  formal caches exist, `HK_ALLOW_HEAVY_TRAINING=1` is set, and the selected GPU
-  has memory.used < 500 MiB. L2 refuses formal evaluation until real HK L1
-  handoff rows exist.

docs/legacy/OLD_l1_README.md

@@ -1,79 +0,0 @@
-# L1 Evaluation Package
-
-L1 is the situation-understanding layer.  It converts recent raw RGB history
-and structured fight state into the belief interface consumed by L2.  The
-current official L1 result is a task-trained ResNet18-GRU belief model plus
-tracker-compatible handoff fields.
-
-## Canonical Question
-
-L1 answers whether the system understands the current fight state:
-
-- player--boss distance,
-- front / decision-zone geometry,
-- cooldown and previous-skill handoff state,
-- whether the belief is usable by L2.
-
-L1 does not choose the next skill and does not render video.
-
-## Standard Subdirectories
-
-```text
-evaluation/l1/
-  model/       # architecture map and source-of-truth files
-  train/       # training split and official training/eval entry points
-  eval/        # official metrics, latency, affordance, handoff checks
-  baselines/   # DINOv2, VideoMAE, latent/engine baselines
-  ckpt/        # checkpoint manifest
-  results/     # canonical result manifest
-```
-
-## Current Official Setup
-
-- Train split: `out/layered/manifest_latent_covered.json`, train rows
-  `18,068`.
-- Test split: `out/layered/manifest.json`, official test rows `8,075`.
-- Visual input: 5 RGB history frames, offsets `[-8, -4, -2, -1, 0]`,
-  frame-in-cell `[2]`, resized to `192 x 336`.
-- Model: task-trained ResNet18 frame encoder + GRU + boss embedding +
-  multi-head belief outputs.
-- Checkpoint:
-  `out/situation/raw_rgb_resnet18_decision_finetune_from_dp_current0_e10.pt`.
-
-## Primary Paper Table
-
-The L1 main table is stored in:
-
-- `paper/l1_results_table_aaai2027_submit.tex`
-- `paper/l1_external_baselines_zh.md`
-
-The table compares:
-
-- DINOv2-S + MLP frozen-backbone baseline,
-- VideoMAE-B + MLP frozen-backbone baseline,
-- PACT-L1.
-
-Main metrics:
-
-- Distance MAE,
-- `d_p@2`,
-- front-cone F1,
-- decision-zone accuracy,
-- batch-8 model-forward latency.
-
-Latency excludes mp4 decoding and is measured on decoded RGB histories.
-
-## Source-of-Truth Registry
-
-Use `evaluation/l1/registry.json` for machine-readable paths to scripts,
-checkpoints, results, feature caches, and table sources.
-
-## Do Not Use For Main Table
-
-These are useful diagnostics but should not be mixed into the primary paper
-table without a separate caption:
-
-- smoke results under `out/situation/*smoke*`,
-- full-manifest foundation probes trained on `22,645` rows,
-- latent-covered test results with `6,013` rows,
-- latency numbers that include mp4 decoding.

docs/legacy/OLD_l1_registry.json

@@ -1,71 +0,0 @@
-{
-  "layer": "L1",
-  "name": "situation_understanding",
-  "status": "official_result_with_external_baselines",
-  "splits": {
-    "official_train_manifest": "out/layered/manifest_latent_covered.json",
-    "official_train_n": 18068,
-    "official_test_manifest": "out/layered/manifest.json",
-    "official_test_n": 8075,
-    "rgb_history_offsets": [-8, -4, -2, -1, 0],
-    "frame_in_cell": [2],
-    "rgb_shape": [5, 3, 192, 336]
-  },
-  "canonical_model": {
-    "name": "PACT-L1",
-    "architecture": "ResNet18 frame encoder + GRU + boss embedding + multi-head belief outputs",
-    "source": "scripts/train_rgb_situation_net.py",
-    "checkpoint": "out/situation/raw_rgb_resnet18_decision_finetune_from_dp_current0_e10.pt",
-    "official_metrics": "out/situation/raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.json",
-    "official_beliefs": "out/situation/beliefs_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl",
-    "handoff": "out/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl",
-    "handoff_summary": "out/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test_summary.json",
-    "affordance": "out/situation/affordance_eval_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.json"
-  },
-  "baselines": [
-    {
-      "name": "DINOv2-S + MLP",
-      "type": "frozen foundation visual backbone",
-      "source": "scripts/eval_l1_foundation_baselines.py",
-      "retrain_source": "scripts/retrain_l1_foundation_probe_from_cache.py",
-      "train_feature_cache": "out/situation/foundation_features/l1_dinov2_small_train_grouped_stream_covered18068_features.pt",
-      "test_feature_cache": "out/situation/foundation_features/l1_dinov2_small_test_grouped_stream_features.pt",
-      "official_metrics": "out/situation/foundation_dinov2_small_covered_train_official_test.json"
-    },
-    {
-      "name": "VideoMAE-B + MLP",
-      "type": "frozen foundation video backbone",
-      "source": "scripts/eval_l1_foundation_baselines.py",
-      "retrain_source": "scripts/retrain_l1_foundation_probe_from_cache.py",
-      "train_feature_cache": "out/situation/foundation_features/l1_videomae_base_train_grouped_stream_covered18068_features.pt",
-      "test_feature_cache": "out/situation/foundation_features/l1_videomae_base_test_grouped_stream_features.pt",
-      "official_metrics": "out/situation/foundation_videomae_base_covered_train_official_test.json"
-    },
-    {
-      "name": "engine oracle / majority / obs-history MLP",
-      "type": "non-visual diagnostic baselines",
-      "summary": "out/layered/l1_summary.csv"
-    }
-  ],
-  "evaluation_scripts": {
-    "build_rgb_cache": "scripts/build_rgb_frame_cache.py",
-    "append_current_rgb": "scripts/append_current_rgb_frame_cache.py",
-    "train_eval_pact_l1": "scripts/train_rgb_situation_net.py",
-    "export_handoff": "scripts/export_l1_handoff_payloads.py",
-    "affordance": "scripts/eval_l1_affordance_metrics.py",
-    "foundation_baselines": "scripts/eval_l1_foundation_baselines.py",
-    "retrain_foundation_probe": "scripts/retrain_l1_foundation_probe_from_cache.py",
-    "latency": "scripts/benchmark_l1_visual_latency.py",
-    "latent_diagnostics": "scripts/eval_l1_latent_understanding.py",
-    "latent_cnn_diagnostics": "scripts/eval_l1_latent_cnn_understanding.py"
-  },
-  "latency": {
-    "definition": "batch-8 model-forward latency on decoded RGB histories; excludes mp4 decoding",
-    "result": "out/situation/l1_visual_latency_benchmark_b8.json"
-  },
-  "paper_sources": {
-    "latex_table": "paper/l1_results_table_aaai2027_submit.tex",
-    "chinese_summary": "paper/l1_external_baselines_zh.md",
-    "preview_pdf": "paper/main.pdf"
-  }
-}

docs/legacy/OLD_l2_README.md

@@ -1,197 +0,0 @@
-# L2 Evaluation Package
-
-L2 is the skill-decision layer. It consumes the L1 belief interface and chooses
-the next boss skill. A valid L2 output must include a machine-readable decision
-and a short rationale:
-
-```json
-{"skill": "ground_slam", "reason": "near distance -> close skill", "confidence": 0.7}
-```
-
-## Canonical Question
-
-L2 answers whether the system can make an effective next-skill decision from
-the L1 belief state:
-
-- choose one legal boss skill,
-- respect cooldown and handoff constraints,
-- use decision-relevant belief fields such as distance, front cone, previous
-  skill, HP phase, and cooldown,
-- provide a rationale that supports the selected skill and is grounded in L1.
-
-L2 does not estimate visual belief fields and does not render video.
-
-## Metric Groups
-
-Use separate groups in paper tables or ablations.
-
-1. Decision quality:
-   - skill match rate,
-   - skill macro recall,
-   - skill-family match rate,
-   - JS divergence to the real skill distribution,
-   - normalized entropy / effective skill count.
-
-2. Interface validity:
-   - JSON/schema valid rate,
-   - legal skill rate,
-   - cooldown-ok rate,
-   - rule-grounded rate.
-
-3. Rationale quality:
-   - non-empty reason rate,
-   - rationale-informative rate,
-   - decision-rationale alignment rate,
-   - rationale-belief grounding rate,
-   - rationale-contradiction rate,
-   - auxiliary CLIP reason--description cosine.
-
-4. Counterfactual reactivity:
-   - distance changes decision rate,
-   - distance monotonic far/close rate,
-   - blocked skill switch rate,
-   - legal/cooldown-ok rate after blocking,
-   - style-conditioned close/far deltas.
-
-5. Skill-description intervention:
-   - No-Desc Flip: whether the paired decision changes after removing skill
-     mechanics descriptions while keeping the same skill names, menu, and
-     cooldowns,
-   - Swap Desc-Follow: whether the paired decision follows the swapped-in
-     mechanics description rather than the original skill name,
-   - Swap Name-Bias: whether the paired decision remains on the original
-     full-prompt skill name after descriptions are swapped.
-
-## Important Evaluation Logic
-
-Decision-rationale semantic relevance is useful, but it is not enough to prove
-decision effectiveness. A rationale can semantically match the selected skill
-while contradicting L1, for example choosing a melee skill because the player is
-close when the belief says the player is far. Therefore L2 reports:
-
-- decision-rationale alignment: whether the reason semantically supports the
-  chosen skill family,
-- rationale-belief grounding: whether the factual claims in the reason are
-  supported by L1,
-- decision quality: whether the selected skill matches the target or target
-  family and satisfies constraints.
-
-CLIP text cosine is reported only as an auxiliary semantic-consistency
-diagnostic. It can show whether a rationale is textually close to a skill
-mechanics description, but it is not a causal test and is weak for fine-grained
-text--text distinctions among similar skill descriptions.
-
-## Current Official Inputs
-
-- Official L1 handoff:
-  `out/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl`
-- Current row-level L2 heuristic predictions:
-  `out/layered/predictions_l2_heuristic_official_test_belief_raw_rgb_l1_handoff.jsonl`
-- Current L2 heuristic summary:
-  `out/layered/l2_heuristic_official_test_belief_raw_rgb_l1_handoff.json`
-
-## Canonical Commands
-
-Decision evaluation:
-
-```bash
-python scripts/eval_l2_decision.py \
-  --backend heuristic \
-  --split test \
-  --beliefs out/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl \
-  --predictions_out out/layered/predictions_l2_heuristic_official_test_belief_raw_rgb_l1_handoff.jsonl \
-  --out out/layered/l2_heuristic_official_test_belief_raw_rgb_l1_handoff.json
-```
-
-Rationale evaluation:
-
-```bash
-python scripts/eval_l2_rationale_alignment.py \
-  --predictions out/layered/predictions_l2_heuristic_official_test_belief_raw_rgb_l1_handoff.jsonl \
-  --out out/layered/l2_rationale_heuristic_official_test_belief_raw_rgb_l1_handoff.json
-```
-
-Counterfactual evaluation:
-
-```bash
-python scripts/eval_l2_counterfactual.py \
-  --backend heuristic \
-  --split test \
-  --beliefs out/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl \
-  --out out/layered/l2_counterfactual_heuristic_official_test_belief_raw_rgb_l1_handoff.json
-```
-
-Skill-description intervention:
-
-```bash
-GEMMA_OPENAI_BASE_URL=http://127.0.0.1:8000/v1 \
-python scripts/eval_l2_skill_description_intervention.py \
-  --backend gemma \
-  --limit 200 \
-  --sample_strategy stratified \
-  --anonymous_names \
-  --resume \
-  --out out/layered/l2_skill_desc_intervention_gemma_anon_n200.json \
-  --rows_out out/layered/l2_skill_desc_intervention_gemma_anon_n200_rows.jsonl
-```
-
-Use `--dry_run_prompts` to audit the prompt triplets without calling a model.
-The intervention changes only `function`, `effect_on_distance`, and `role`; it
-keeps the same skill menu, anonymous skill IDs, cooldowns, and L1 belief.
-
-Decision-summary generation:
-
-```bash
-python scripts/summarize_l2_intervention_for_paper.py \
-  --anonymous_rows out/layered/l2_skill_desc_intervention_gemma_anon_n200_rows.jsonl \
-  --out_json out/layered/l2_skill_desc_intervention_paper_summary_n200.json \
-  --out_tex /tmp/l2_decision_semantic_control_check.tex
-```
-
-Rationale-decision consistency:
-
-```bash
-python scripts/eval_l2_rationale_consistency.py \
-  --rows out/layered/l2_skill_desc_intervention_gemma_anon_n200_rows.jsonl \
-  --out_json out/layered/l2_rationale_consistency_gemma_anon_n200.json \
-  --out_tex paper/l2_rationale_consistency_rows.tex
-```
-
-Formal L2 table generation:
-
-```bash
-python scripts/build_l2_formal_table.py \
-  --decision_summary out/layered/l2_skill_desc_intervention_paper_summary_n200.json \
-  --rationale_summary out/layered/l2_rationale_consistency_gemma_anon_n200.json \
-  --out_tex paper/l2_skill_description_intervention_table.tex
-```
-
-CLIP reason--description similarity:
-
-```bash
-HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 \
-python scripts/eval_l2_clip_reason_similarity.py \
-  --predictions out/layered/l2_skill_desc_intervention_gemma_anon_n30_rows.jsonl \
-  --out out/layered/l2_clip_reason_similarity_gemma_anon_n30.json
-```
-
-The default evaluation masks skill names and anonymous IDs from rationales
-before CLIP encoding. CLIP is an auxiliary diagnostic and is not the formal main
-L2 result.
-
-## Paper Table Shape
-
-For the main paper, use compact numeric columns:
-
-```text
-Method | Belief | Skill MR | Family Acc. | Legal | Cooldown | R-D Align. | R-B Ground. | CF Switch
-```
-
-Where `R-D Align.` is rationale-decision alignment and `R-B Ground.` is
-rationale-belief grounding. Keep long explanations out of table cells.
-
-For the description-sensitivity ablation, keep it separate and short:
-
-```text
-Setting / subset | n | No-Desc Flip | Desc-Follow | Name-Bias
-```

docs/legacy/OLD_l2_registry.json

@@ -1,80 +0,0 @@
-{
-  "layer": "L2",
-  "name": "skill_decision",
-  "status": "core_metrics_reset_to_description_change_and_llm_judge",
-  "official_belief_source": "out/situation/l1_handoff_raw_rgb_resnet18_decision_finetune_from_dp_current0_e10_official_test.jsonl",
-  "canonical_methods": [
-    {
-      "name": "heuristic",
-      "type": "deterministic distance/cooldown policy",
-      "decision_script": "scripts/eval_l2_decision.py",
-      "official_summary": "out/layered/l2_heuristic_official_test_belief_raw_rgb_l1_handoff.json",
-      "official_predictions": "out/layered/predictions_l2_heuristic_official_test_belief_raw_rgb_l1_handoff.jsonl",
-      "rationale_eval": "out/layered/l2_rationale_heuristic_official_test_belief_raw_rgb_l1_handoff.json",
-      "counterfactual_eval": "out/layered/l2_counterfactual_heuristic_official_test_belief_raw_rgb_l1_handoff.json"
-    },
-    {
-      "name": "belief_mlp",
-      "type": "learned policy over structured belief fields",
-      "decision_script": "scripts/eval_l2_belief_policy.py",
-      "representative_summary": "out/layered/l2_belief_mlp_test_all_covered_belief_latent_cnn_gru_full_e24.json",
-      "representative_predictions": "out/layered/predictions_l2_belief_mlp_test_all_covered_belief_latent_cnn_gru_full_e24.jsonl"
-    },
-    {
-      "name": "gemma",
-      "type": "LLM skill selector with strict JSON output",
-      "decision_script": "scripts/eval_l2_decision.py",
-      "closed_loop_script": "scripts/l2_gemma_decide.py",
-      "skill_description_intervention": {
-        "official_anonymous_ids_n200": "out/layered/l2_skill_desc_intervention_gemma_anon_n200.json",
-        "official_anonymous_ids_n200_rows": "out/layered/l2_skill_desc_intervention_gemma_anon_n200_rows.jsonl",
-        "official_paper_summary_n200": "out/layered/l2_skill_desc_intervention_paper_summary_n200.json",
-        "required_belief_views": [
-          "full",
-          "compact"
-        ],
-        "core_metrics": [
-          "no_desc_decision_change_rate",
-          "swap_desc_decision_change_rate"
-        ],
-        "original_names_n30": "out/layered/l2_skill_desc_intervention_gemma_n30.json",
-        "anonymous_ids_n30": "out/layered/l2_skill_desc_intervention_gemma_anon_n30.json",
-        "clip_original_names_n30": "out/layered/l2_clip_reason_similarity_gemma_n30.json",
-        "clip_anonymous_ids_n30": "out/layered/l2_clip_reason_similarity_gemma_anon_n30.json",
-        "latex_table": "paper/l2_skill_description_intervention_table.tex",
-        "clip_latex_table": "paper/l2_clip_reason_similarity_table.tex",
-        "chinese_summary": "paper/l2_skill_description_intervention_zh.md",
-        "clip_chinese_summary": "paper/l2_clip_reason_similarity_zh.md"
-      }
-    }
-  ],
-  "evaluation_scripts": {
-    "decision": "scripts/eval_l2_decision.py",
-    "belief_mlp": "scripts/eval_l2_belief_policy.py",
-    "skill_description_intervention": "scripts/eval_l2_skill_description_intervention.py",
-    "intervention_paper_table": "scripts/summarize_l2_intervention_for_paper.py",
-    "llm_judge": "scripts/eval_l2_llm_judge.py",
-    "formal_l2_table": "scripts/build_l2_formal_table.py",
-    "analysis": "scripts/analyze_l2_predictions.py",
-    "calibration": "scripts/analyze_l2_rule_calibration.py"
-  },
-  "paper_tables": {
-    "skill_description_intervention": "paper/l2_skill_description_intervention_table.tex",
-    "rationale_consistency": "out/layered/l2_rationale_consistency_gemma_anon_n200.json"
-  },
-  "primary_metrics": [
-    "no_desc_decision_change_rate",
-    "swap_desc_decision_change_rate",
-    "llm_judge_selected_acceptable_rate"
-  ],
-  "paper_table_policy": {
-    "main_table": "numeric compact columns only",
-    "semantic_similarity": "not a current core metric",
-    "required_separation": [
-      "description-removal decision change",
-      "description-swap decision change",
-      "independent LLM judge decision quality",
-      "full vs compact L1 input view"
-    ]
-  }
-}

env.sh

@@ -5,9 +5,8 @@ BENCH="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 export BENCH
 cd "$BENCH"
 
-# L2 需要一个常驻的 Gemma OpenAI 兼容服务（必须用 gemma4-venv 环境起，
-# 其它环境的 transformers 版本没有 Gemma4 类）：
-#   /dev_vepfs/junhaochen/envs/gemma4-venv/bin/python pact/gemma_server.py
+# L2 需要一个常驻的 Gemma OpenAI 兼容服务。服务环境和便携式启动命令见
+# docs/REPRODUCE.md；不要在这里写机器专用的 Python 或模型绝对路径。
 export GEMMA_OPENAI_BASE_URL="${GEMMA_OPENAI_BASE_URL:-http://127.0.0.1:8018/v1}"
 export GEMMA_MODEL="${GEMMA_MODEL:-gemma-4-E2B-it}"
 export GEMMA_TEMPERATURE="${GEMMA_TEMPERATURE:-0}"

evaluation/ablations/pact_eval_v1_20260709/vrising_experiment_status.md

@@ -1,25 +0,0 @@
-# V Rising Evaluation Implementation Status
-
-## L1 Main Comparison
-
-| Method | Train n | Test n | Dist. MAE | dp@2 | Front F1 | Zone Acc. | Lat. ms |
-|---|---:|---:|---:|---:|---:|---:|---:|
-| DINOv2-S + MLP | 18068 | 8075 | 0.7016 | 0.9336 | 0.8822 | 0.7538 | 4.2276 |
-| VideoMAE-B + MLP | 18068 | 8075 | 0.6858 | 0.925 | 0.8706 | 0.7324 | 20.1978 |
-| PACT-L1 | 18068 | 8075 | 0.2621 | 0.9962 | 0.9227 | 0.8406 | 0.832 |
-
-## L1 Image Ablation
-
-| Metric | +img PACT-L1 | -img strict prior | Delta |
-|---|---:|---:|---:|
-
-## L2 Semantic Intervention
-
-| Belief view | Status | n | No-desc change | Swap-desc change | Desc-follow | Name-bias |
-|---|---|---:|---:|---:|---:|---:|
-| full_existing_legacy_metadata | missing | None | MISSING | MISSING | MISSING | MISSING |
-| full | complete | 200 | 43.7% | 87.8% | 78.7% | 12.2% |
-| compact | complete | 200 | 54.4% | 90.2% | 85.9% | 9.8% |
-
-## Blockers
-

games/hk/README.md

@@ -1,111 +1,69 @@
 # Hollow Knight
 
-3 个 boss 的 2D 横版战斗。主线（数据 / L1 / L2）齐全，另外**独有一个历史帧消融**（V Rising 没做）。
+Hollow Knight contributes False Knight, Hive Knight, and Hornet. Its official
+test split contains 30 fight-disjoint fights. The compact L2 interface uses
+distance and an explicit player-relative side derived from the trained angle
+head.
 
-## 1. 数据是怎么构造的
+## Data
 
-```
+```text
 data/hk/processed/{FalseKnight,HiveKnight,Hornet}/
-    policy_view_fight{N}.jsonl   ← 决策行：action + obs
-    render_view_fight{N}.jsonl   ← 渲染 prompt → 技能机制描述的来源
-    video_fight{N}.mp4
 ```
 
-**切分：fight 级**，每个 boss 按 fight 排序，**最后 10 场 test、前 3 场 val**、其余 train。整场对局为单位，无帧泄漏。
-
-| boss | 总 fight | train / val / test | 技能数 |
-|---|---:|---|---:|
-| FalseKnight | 226 | 213 / 3 / 10 | 6 |
-| HiveKnight | 77 | 64 / 3 / 10 | 6 |
-| Hornet | 220 | 207 / 3 / 10 | 7 |
-| **合计** | **523** | **484 / 9 / 30** | |
-
-**官方测试 8,360 行**（30 场）。平均可选技能数 K̄ = 3.42 → **L2 随机基线 29.2%**。
-
-**距离量纲**：引擎单位，用默认 `--distance_norm 30`。
-
 ```bash
-bash    games/hk/data/audit_dataset.sh     # → results/hk/dataset_audit.json
-python3 games/hk/data/build_metadata.py    # → games/hk/{ontology,skill_library}.json
-bash    games/hk/data/build_manifest.sh    # → games/hk/manifest.json
+bash games/hk/data/audit_dataset.sh
+python3 games/hk/data/build_metadata.py
+bash games/hk/data/build_manifest.sh
 ```
 
-技能机制描述来自 `render_view` 的 prompt 短语，冷却/时长统计来自 `policy_view` 日志行 —— **不是人手编的**。
-只有 `build_metadata.py` 里的 `MECHANICS` 表是 HK 特有的，其余推导逻辑共享 `pact/build_game_metadata.py`。
-
-## 2. 做了哪些实验
-
-| 实验块 | 状态 | 入口代码 | 产物 |
-|---|---|---|---|
-| 数据审计与切分 | ✅ | `games/hk/data/*.sh` `build_metadata.py` | `results/hk/dataset_audit.json` |
-| L1 官方评测（主结果） | ✅ | `games/hk/l1/{train_l1,eval_official_from_ckpt}.sh` | `results/hk/l1_main_official_test.json` |
-| **L1 消融：历史帧** | ✅ | `games/hk/l1/train_l1.sh`（`history_offsets=0`） | `results/hk/l1_ablation_curframeonly_official_test.json` |
-| L2 机制语义干预（compact + full） | ✅ | `games/hk/l2/run_semantic_views.sh` | `results/hk/eval_runs/L2-SEMANTIC-INTERVENTION_*_samplev2_*` |
-| L1 主对比（DINOv2/VideoMAE 基线）※ | ✅ | `games/hk/l1/run_foundation_baselines.sh` | `results/hk/l1_baseline_*_official_test.json` |
-| L1 预测可信度（无图先验） | ✅ | `games/hk/l1/run_img_ablation.sh` | `results/hk/eval_runs/L1-IMG-ABLATION/` |
-| L1 筛选字段（belief probe） | ✅ | `games/hk/l1/run_belief_probe.sh` | `results/hk/eval_runs/L1-FIELD-SELECTION/` |
-| L2 图像模态消融（60 状态配对） | ✅ | `games/hk/l2/run_image_modality_ablation.sh`（`--limit 60`） | `results/hk/eval_runs/L2-IMAGE-MODALITY-ABLATION_*` |
-| **L2 理由-决策对应（核心）** | ✅ | `games/hk/l2/run_rationale_consistency.sh` | `results/hk/eval_runs/L2-RATIONALE-CONSISTENCY_*` |
-| L2 决策质量（LLM judge） | ⏸ 暂缓 | — | 口径未定 |
-
-> ※ **基线口径（重要）**：基线是冻结主干 + 轻量 probe，PACT-L1 是端到端从零训。两者含「端到端 vs 冻结」这一项差异，故成立的命题是「**任务专训的小网优于冻结的通用视觉特征（作为 belief 抽取器）**」，**不是**「架构 > DINOv2」。要隔离该混淆需补一个基础模型端到端微调的对照（待做）。数据/历史/考卷已对齐（balanced 全 boss、同 5 帧、同 8360）。
->
-> V Rising 独有的 **L2 模型消融 / L1 延迟基准 / CLIP 诊断**本游戏未做（聚焦核心块）。完整三游戏清单见 [顶层 README](../../README.md#完整实验清单权威来源) 或 `python3 registry/status.py`。
-
-## 3. ckpt
-
-| ckpt | 用途 |
-|---|---|
-| `ckpt/hk/l1_main_train30k_e10.pt` | **主结果**。5 帧历史（−8/−4/−2/−1/0），30k 训练样本，10 epoch |
-| `ckpt/hk/l1_ablation_curframeonly_e10.pt` | 消融：**只输入当前帧**（同架构、同训练集、同 10 epoch） |
-
-## 4. 结果
+## L1
 
-**L1**（official test，n = 8,360）
+Published checkpoints:
 
-| 指标 | 值 |
-|---|---:|
-| 距离 MAE | 0.4695 |
-| dp@2 | 0.9726 |
-| 角度 MAE | **3.6488°** |
-| angle@20° | **0.9792** |
-| distance_bin acc | 0.7243 |
-| angle_bin acc | **0.0000** ⚠️ 见下 |
-
-**L1 历史帧消融**（旧口径 test，n = 2,242，两边同口径可比）
-
-| 输入 | 距离 MAE | 角度 MAE | angle@20° |
-|---|---:|---:|---:|
-| 5 帧历史 | 0.5160 | — | — |
-| 仅当前帧 | 0.5478 | 3.8737° | 0.9737 |
-
-→ **几何主要由当前帧承载**：去掉历史，距离 MAE 只退化约 6%，角度几乎不变。历史帧有贡献但非必需。
+```text
+ckpt/hk/l1_main_train30k_e10_provenance_v2.pt
+ckpt/hk/l1_ablation_curframeonly_e10.pt
+ckpt/hk/l1_matched_foundation10k_seed0_e10.pt
+```
 
-**L2 机制语义干预**（gemma-4-E2B-it，温度 0，200 状态，匿名技能 ID，`L2-SAMPLE-200-v2`，30 场覆盖）
+Primary entry points:
 
-| belief 视图 | 跟随描述 | 抹除后翻转 | 交换后翻转 | 名字偏见 |
-|---|---:|---:|---:|---:|
-| **compact**（正典 v3） | **76.2%**（2.61× 随机 29.2%） | 92.2% | 89.6% | 10.4% |
-| full（过全 belief 对照 v3） | 47.5%（1.63×） | 89.3% | 94.5% | 5.5% |
+```bash
+bash games/hk/l1/eval_official_from_ckpt.sh
+bash games/hk/l1/run_foundation_baselines.sh
+bash games/hk/l1/run_matched_foundation10k.sh
+bash games/hk/l1/run_img_ablation.sh
+```
 
-> **勘误（2026-07-14）**：v2 版输入被未训练头污染（prev/hp 96%+ 错），曾使 HK 虚高（compact follow 89.8→76.2）。
-> v3 = 修复后干净输入 + menu≥2 口径；v2 存档于 samplev2 目录仅作 A/B。
+The matched comparison binds exactly 10,000 ordered training rows and all 8,360
+official test rows across PACT-L1, DINOv2-S, and VideoMAE-B. The 30k checkpoint
+is the canonical L1 handoff for downstream L2 evaluation.
 
-两个结论：
+## L2
 
-1. HK 是三个游戏里 L2 最干净的：抹掉机制描述几乎必然改变决策（89.4%），名字偏见只有 3.0%（三游戏最低）。
-2. **compact 远优于 full，落差 −28.7 点**（V Rising 只有 −8.3 点）——干净数据下结论不变。full 的交换后翻转仍有 94.5%：决策照样会变，只是不再跟着描述走。
+The canonical compact protocol is balanced-v3 / HP-free-v6 /
+samplev6-side with 200 states.
 
+```bash
+bash games/hk/l2/run_semantic_views.sh
+bash games/hk/l2/run_rationale_consistency.sh
+bash games/hk/l2/run_image_modality_ablation.sh
+```
 
-**L2 理由-决策对应**（核心指标，确定性审计，同一批 200 状态，compact）
+The fixed two-choice control uses:
 
-| 点名对应(覆盖) | 机制重构 | 换述忠实 | 矛盾率 |
-|---:|---:|---:|---:|
-| 100% (45%) | 75.3% | 100.0% | 11.6% |
+```bash
+HK_MENU_POLICY=counterfactual_two \
+HK_RUN_TAG=test10_samplev6_side_explicit_twochoice \
+  bash games/hk/l2/run_semantic_views.sh
+```
 
-四组件+三重负对照定义见 `pact/eval_l2_rationale_consistency.py` 头注释；负对照（no_desc / 错位理由）均塌向随机，指标有区分度。
+Published L2 inputs and outputs are rooted at:
 
-## 5. 已知问题
+```text
+results/hk/beliefs_l1_main_official_test_compact_side_v1.jsonl
+results/hk/eval_runs/
+```
 
-- **`player_angle_bin` 分类头 acc = 0.0000** —— 是这个 bin 头本身坏了（连续角度 3.65° 完全正常，同一个头在 V Rising 是 0.72、Isaac 是 0.79）。**未修**。
-  不影响 L2：compact 视图不含该字段。
+See `docs/EXPERIMENTS.md` for the current numbers and interpretation.

games/hk/config.json

@@ -2,8 +2,8 @@
   "game_id": "hk",
   "hf_repo": "teawhite/vrising",
   "processed_root": "data/hk/processed",
-  "ontology_path": "out/hk/ontology.json",
-  "skill_library_path": "schemas/hk_skill_library.json",
+  "ontology_path": "games/hk/ontology.json",
+  "skill_library_path": "games/hk/skill_library.json",
   "entities": [
     "FalseKnight",
     "HiveKnight",
@@ -12,7 +12,7 @@
   "split_policy": {
     "unit": "fight",
     "val_count": 3,
-    "test_count": 3,
+    "test_count": 10,
     "rule": "sorted fights; test is last N, val is preceding M"
   },
   "l1": {
@@ -36,13 +36,12 @@
   },
   "l2": {
     "sample_size": 200,
-    "sample_strategy": "stratified",
+    "sample_strategy": "balanced boss/fight/distance stratified v3",
     "belief_views": [
-      "full",
       "compact"
     ],
     "model_id": "gemma-4-E2B-it",
     "temperature": 0
   },
-  "status": "data_audit_ontology_skill_library_and_manifest_ready_l1_l2_training_blocked"
+  "status": "official_test10_l1_l2_available"
 }

games/hk/data/README.md

@@ -1,14 +0,0 @@
-# HK Data
-
-Expected location after download:
-
-`data/hk/processed`
-
-The processed directory should contain one subdirectory per controllable entity
-with `video_fight*.mp4`, `policy_view_fight*.jsonl`, `render_view_fight*.jsonl`,
-and `dataset_manifest.json`.
-
-`build_metadata.py` derives `games/hk/ontology.json` and
-`games/hk/skill_library.json` from HK policy rows and render prompts.  The
-skill mechanics are conservative data-derived descriptions, not human-validated
-game-design annotations.

games/hk/l1/README.md

@@ -1,8 +0,0 @@
-# HK L1
-
-HK L1 should be trained independently from V Rising.  The HK dataset audit and
-manifest are ready, and a 24-sample RGB cache smoke test passed.
-
-`train_l1.sh` is a guarded entry point. It refuses to start heavy training until
-formal HK train/test RGB caches exist, `HK_ALLOW_HEAVY_TRAINING=1` is set, and
-the selected GPU is idle enough.

games/hk/l1/run_matched_foundation10k.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)"
+cd "$ROOT"
+bash pipelines/l1/train/run_hk_matched_foundation10k.sh

games/hk/l1/run_train30k_pipeline.sh

@@ -14,9 +14,9 @@ GPU_WAIT_SECONDS="${GPU_WAIT_SECONDS:-300}"
 
 TRAIN_CACHE="${TRAIN_CACHE:-out/hk/situation/raw_rgb_train30k_current0_h192w336.pt}"
 TEST_CACHE="${TEST_CACHE:-out/hk/situation/raw_rgb_test_official_current0_h192w336.pt}"
-OUT_JSON="${OUT_JSON:-out/hk/situation/raw_rgb_resnet18_decision_train30k_from_dp_current0_e10_official_test.json}"
-BELIEF_OUT="${BELIEF_OUT:-out/hk/situation/beliefs_raw_rgb_resnet18_decision_train30k_from_dp_current0_e10_official_test.jsonl}"
-CKPT_OUT="${CKPT_OUT:-ckpt/hk/l1_main_train30k_e10.pt}"
+OUT_JSON="${OUT_JSON:-results/hk/l1_main_official_test.json}"
+BELIEF_OUT="${BELIEF_OUT:-results/hk/beliefs_l1_main_official_test_compact_side_v1.jsonl}"
+CKPT_OUT="${CKPT_OUT:-ckpt/hk/l1_main_train30k_e10_provenance_v2.pt}"
 
 mkdir -p out/hk/situation out/hk/logs
 

games/hk/l2/README.md

@@ -1,50 +0,0 @@
-# HK L2
-
-Semantic intervention: swap the mechanic description of skill A onto skill B and
-check whether the decision follows the swapped semantics instead of the skill
-identity.
-
-## Canonical setting
-
-- `belief_view=compact` (the Fig. 1 interface).
-- `gemma-4-E2B-it`, temperature 0, 200 stratified states, anonymous skill IDs.
-- Variants per state: `full` / `no_desc` / `swap_desc`.
-
-L2 consumes the flat L1 beliefs directly (`out/hk/situation/beliefs_*.jsonl`).
-There is no separate handoff file.
-
-## Run
-
-Needs a Gemma OpenAI-compatible endpoint on `GEMMA_OPENAI_BASE_URL`
-(default `http://127.0.0.1:8018/v1`, started from the `gemma4-venv` env).
-
-```bash
-bash games/hk/l2/run_semantic_views.sh
-```
-
-Writes `metrics.json`, `rows.jsonl`, and `run_config.json` under
-`results/hk/eval_runs/L2-SEMANTIC-INTERVENTION_gemma-4-E2B-it_compact_.../`.
-
-## Result (n=200, verified)
-
-| metric | compact |
-|---|---|
-| no-description change | 92.4% |
-| swapped-description change | 98.0% |
-| **desc-follow** | **95.0%** |
-| neither (noise) | 1.0% |
-| valid (on-menu) | 99.0% |
-
-Random follow baseline is 29.2% (mean menu size 3.42), so compact is 3.25x
-chance. Per boss: FalseKnight 95.6%, HiveKnight 97.0%, Hornet 92.2%.
-
-`name_bias` is not reported as independent evidence: it is identically
-`100% - swap_change`, so it restates the change rate rather than adding
-information. The informative split is desc-follow vs neither.
-
-## Kept for reference, not canonical
-
-A `belief_view=full` run exists under `results/hk/eval_runs/..._full_.../` (desc-follow
-62.4%, neither 33.5%). It is the evidence for "compact beats full" and is cited in
-the summary deck, but it is not part of the canonical HK L2 setting. To reproduce
-it: `HK_BELIEF_VIEW=full bash games/hk/l2/run_semantic_views.sh`.