# VeriHarness v0.5 — Verification-Prompt Study (GOAL_SPEC)

本目录是完全独立的实验 subproject，与 v0.x 隔离；只共享项目核心主张，统计绝不与旧版本混合。这是目前最正式的一次实验。

## 研究问题

正式对比不同 **verification prompt** 版本，验证在 image→HTML 的 agentic coding loop 中显式加入多模态验证环节的作用。

本研究的核心叙事和后续 verification 设计原则记录在
[`CORE_STORY.md`](CORE_STORY.md)：

> Visual coding agent 与一般 coding agent 共享
> Explore/Ground → Locate → Repair → Verify → Repeat → Accept 的工作循环；
> 区别在于视觉 specification 必须先从 reference 中 ground 并表达为
> Visual Unit Tests。

## 条件矩阵

| 层 | 条件 | 组成 | 交付 | MCP |
| --- | --- | --- | --- | --- |
| A — 整体地板 | `A-raw` | task prompt 单独 | `claude -p <task>`（user delivery） | 无 |
| B — 验证底座 | `B-base` | tool prompt + task prompt + CallMLLM | append-system | 有 |
| V — 实验组 | `V1..Vn`（待设计） | B-base + 各 verification prompt | append-system | 有 |

- A-raw 与 B-base 共享**同一份 task prompt**，只差在有无 tool prompt / CallMLLM MCP。
- A-raw 不禁止 agent 自发 render、Read 自己的 render——那是模型自然行为。
- V 系列的 verification prompt 完全重新设计，与历史 V/W/X 系列无继承关系。

## 固定不变量（科学控制）

- task prompt：`task-V05-faithful-nohack`（见 `prompts/task/V05_faithful_nohack.md`），A/B/V 共享。
- render 管道：per-case 原生像素尺寸，Chromium headless，device_scale_factor=1。
- **跨模型 prompt 字节一致**：opus 与 gpt 除 `--model` 外 prompt 完全相同。
- **2 replicate 可复现**：固定 schedule seed=20260723，cell 级调度。

## 模型三条独立路径

- Generator（每条件都跑两个）：`claude-opus-4-8` 与 `gpt-5.6-sol`（后者经 Anthropic→TRAPI proxy）。
- Runtime verifier（loop 内 CallMLLM 目标）：`gemini-3.1-pro`。
- Offline scorer（最终打分）：同一 gemini + **冻结 rubric**，cell 结束后运行，**不回喂**生成。

三条路径互不重叠，避免自我印证。

## 数据

- 8 cases：case1, case5, case6, case7, case8, case9, case10, case12（复用旧有效集，用户确认）。
- 每 case 含 `reference.png` + `gold-rubrics.json` + `discovery-rubrics.json`。
- **本次将 discovery rubric 纳入打分**（gold + discovery 合并，等权，per-case 归一化），这是与旧实验的关键区别。
- 冻结哈希见 `data/dataset-manifest.json`。

## 停止条件

无时间、无 turn 限制——目标是观察 verification 能力的**上限**。`watchdog_seconds` 设为极大值仅作基础设施兜底。

## 打分

offline scorer 对最终 render 逐条判定 gold+discovery rubric（pass/fail），score = round(pass_rate × 5, 2)，per-case 归一化后跨 case 聚合。

## Verification 设计工作记录

V1..Vn 的详细概念拆分、已确认原则、延后项和开放问题记录在
[`docs/verification-design.md`](docs/verification-design.md)。该文件是
**Deep Spec**，不是 runtime prompt；实际 verification prompt 将保持简短、
meta-level，并让模型自主选择具体执行方式。

其中 [`CORE_STORY.md`](CORE_STORY.md) 是更上层的叙事和设计约束；
`verification-design.md` 负责把这条故事线展开为具体维度、prompt 条件和
实验问题。

当前不预先冻结完整 ladder 顺序。Round 1 baseline 轨迹已指向
finding→repair→re-verification 的闭环缺口，因此选定
[`V1 Visual Unit Test–Driven Correction Loop`](prompts/verification/v05/V1_visual_unit_test_correction_loop.md)
作为首个候选；V2 及后续条件仍根据下一轮真实失败选择。八个 case 同时
服务于行为理解和量化评分，因此研究结论按探索性、迭代式证据解释。

## 运行顺序（骨架阶段，仅两 baseline）

```bash
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/playwright install chromium
.venv/bin/python -m pytest -q          # 30 passed: v0.5 契约 + 通用代码
```

生成（opus）：

```bash
veriharness-v05 run-generation \
  --manifest experiments/v05-baselines-claude-opus-4-8.yaml \
  --run-root runs/v05-baselines-opus
```

gpt 需先启动本目录的 Anthropic→TRAPI proxy，并把 Claude CLI 的 Anthropic base URL 指向它，再跑 `experiments/v05-baselines-gpt56-sol-trapi.yaml`。endpoint/token 只从环境注入，不写进 manifest 或日志。

## 开放项

- V1：候选 prompt 已落盘，正式运行前复核并冻结。
- Verification prompt V2..Vn：根据 V1 轨迹逐步设计。
- Gemini endpoint 协议核实：CallMLLM provider 目前走 Anthropic `/v1/messages`；若 gemini 只认 OpenAI `/chat/completions`，需在 `mllm.py` 加 OpenAI provider。