# Goal Benchmark 工具箱

四步：**读上游契约 → 写维度表 → 挂进契约并校验 → 写回执**。

> 🚨 **发 JSON 的铁律**：任何带 JSON 的内容，一律用**文件写入工具**直接写文件，
> **绝不在 bash 命令里内联 JSON 字符串**（多重双引号会让工具调用崩溃并陷入死循环）。
> 大块内容一律先落文件，再用 `put --file` / `--ref` 交给 CLI。

---

## 1. 读上游契约

```bash
R=data/companies/<公司ID>/runs/<rootRunId>
cat $R/artifacts/task-goal.json                        # 回扣的基准是它，不是 PRD
cat <提示词给的 prd 节点目录>/contract.json             # features[].acceptance_hint / error_cases
cat <提示词给的 sdd 节点目录>/contract.json             # interfaces / data_shapes / error_mapping
ls  $R/artifacts/                                      # 别人已经写了哪几段
```

❌ 提示词没给到路径的节点目录一律不要翻（§四.A.5 隔离规则）。

## 2. 写维度表到共享产物区

用文件写入工具写 `$R/artifacts/goal-benchmark.json`（形状见 `agent.md`）。
**这是你唯一有权写进共享区的文件**（`writesArtifacts: true` 只给了你这一格特权）。

## 3. 挂进契约 + 校验（`server/services/goal-contract.js` 的 CLI）

```bash
# 合并进 acceptance.json 的 benchmark 段（合并，不覆盖别人写的段）
node server/services/goal-contract.js put --run-dir $R \
  --section benchmark --ref goal-benchmark.json \
  --goal-id <task-goal 的 id> --created-by goal-benchmark

# 形状体检：权重和≠1 / 维度重名 / 类型错 / $ref 指不到文件，都在这里被挡
node server/services/goal-contract.js validate --run-dir $R
```

退出码：`0` = 合法；`1` = 契约非法（照它打印的 `[rule] detail` 逐条改，改完再跑）；
`2` = 跑不出结论（没契约 / 参数错）。

**必须跑到 0 才算做完。** `put` 会打印 `contract_hash` 和当前已有的 sections，
把 hash 抄进你的 `attempt-<n>.json`。

⚠️ **绝不要自己手写 `$R/artifacts/acceptance.json`**——它是三段合成的，
手写会把 `test_data` / `test_script` 段整段抹掉。永远走 `put`。

## 4. 写回执

用文件写入工具写 `$R/nodes/<你的 nodeRunId>/attempt-<n>.json`（形状见 `agent.md`）。
`<n>` 是本轮 attempt 序号；**不要覆盖上一次 attempt 的文件**。

## 你**不该**用的工具

| 别用 | 为什么 |
|---|---|
| `goal-contract.js run` | 那是**判卷**，是 `benchmark-validator` 的活。你出题时被测产物还不存在 |
| `put --section test_data` / `--section test_script` | 只写你自己那一段；另外两段有另外的产出节点 |
| 手写 / 覆盖 `artifacts/acceptance.json` | 会抹掉别人写的段。永远走 `put` |
| 写代码 / 跑服务 / 跑测试 | 你产出的是标准，不是产物也不是判决 |
| `node bin/lemon.js task transition` | 阶段流转由**图的边**提供（§九bis） |
| 读提示词没给到的节点目录 | 隔离规则 |
| 直接写 `data/` 下的 sqlite | 状态由引擎从你的 `attempt-<n>.json` 里读走并落库 |