# Validator Reflection 工具箱

你的活只有三步：**读证据 → 写归因 JSON → 结束**。工具用得越少越好。

> 🚨 **发 JSON 的铁律**：任何带 JSON 的内容，一律用**文件写入工具**直接写文件，
> **绝不在 bash 命令里内联 JSON 字符串**（多重双引号会让工具调用崩溃并陷入死循环）。
> JSON 里不许出现真实换行符，`remediation_note` 的换行写成 `\n`。

---

## 1. 读证据（只读这三处）

```bash
# a) 任务级共享产物区（只读，跨 org node 可读）
ls  data/companies/<公司ID>/runs/<rootRunId>/artifacts/
cat data/companies/<公司ID>/runs/<rootRunId>/artifacts/goal-benchmark.json

# b) 你自己的节点目录（可读可写）
ls  data/companies/<公司ID>/runs/<rootRunId>/nodes/<你的 nodeRunId>/
```

c) 失败上下文（哪个节点失败、第几 attempt、失败摘要、上一轮 `remediation_note`）
**由引擎在提示词里带给你**，不需要你去查。

❌ **不要读** `runs/<rootRunId>/nodes/<别的 nodeRunId>/`——节点私有目录彼此隔离
（[27-P3/P4](../../../docs/todo/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。
提示词里没给够的证据，就是「证据不足」，输出 `inconclusive`，不要自己翻墙去找。

## 2. 写归因产出（唯一的写动作）

用文件写入工具写：

```
data/companies/<公司ID>/runs/<rootRunId>/nodes/<你的 nodeRunId>/attempt-<n>.json
```

格式见 `agent.md`「产出格式」一节（`schema: "validator-reflection/v1"`）。
`<n>` 用本节点当前的 attempt 序号；**不要覆盖上一次 attempt 的文件**——归因过程本身要可审计。

写完只回一句话总结：`fail_reason` + 指认了谁 + 一句理由。不要把整份 JSON 复述一遍。

## 3. 需要看契约怎么执行时

验收契约（`goal-benchmark` / `goal-test-data` / `goal-test-script`）的**执行**归
`server/services/goal-contract.js` 管，格式以它为准。你只**读**契约内容当证据，
不要自己发明契约字段，也不要自己去跑执行器——跑契约是 `benchmark-validator` /
`testdata-validator` 那几个节点的活。

---

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

| 别用 | 为什么 |
|---|---|
| 任何写代码 / 改文档的工具 | 你是法医，不是修理工。一行都不改 |
| `node bin/lemon.js task dispatch`（尤其是发给 `innovator`） | 判了 `skill_defect` 也**只挂起等人工**，L4 是 P3 非目标 |
| 训练 / 进化 / retrain 相关的一切 | 同上 |
| 直接写 `data/` 下的 sqlite | `fail_reason` / `remediation_note` 由引擎从你的 JSON 里读走并落库，不用你动手 |
| 读别的节点的 `nodes/{其他}/` | 隔离规则，见上 |
| 给出「任务达成/未达成」的结论 | 那是 `org-validator` 整体的判决，不是你的 |