# Org Validator 工具箱

四步：**读契约 → 跑契约 → 拿归因 → 写判决**。

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

---

## 1. 读验收契约（`artifacts/`，只读）

```bash
R=data/companies/<公司ID>/runs/<rootRunId>
cat $R/artifacts/acceptance.json          # ← 唯一契约入口，先读它
ls  $R/artifacts/ $R/artifacts/goal-test-data/ $R/artifacts/goal-test-script/
cat $R/artifacts/goal-benchmark.json      # acceptance.json 里写 {"$ref": ...} 时，大块内容在这些外置文件里
```

**`acceptance.json` 是唯一入口**：三段（`benchmark` / `test_data` / `test_script`）由
`goal-benchmark` / `goal-test-data` / `goal-test-script` 三个节点各写自己那一段合并而成，
每段要么内联、要么写成 `{"$ref": "<artifacts 下的相对路径>"}` 指向外置文件。
只 `cat` 外置文件会漏掉内联的那几段——**先读 `acceptance.json`，再按需要跟 `$ref` 去读外置文件**。

三段契约由 `org-planner` 的 work graph 产出，你是**跨 org node 的只读消费者**。
**只读**——往 `artifacts/` 写是产出者的特权动作，不是你的。

## 2. 跑契约（**用执行器跑，不要自己拼命令**）

契约的统一格式与执行器是 `server/services/goal-contract.js`。它自带 CLI，**这就是你跑契约的唯一方式**：

```bash
# 被测产物 = 上游交付节点的 output_ref（本次调用的提示词里给了路径）
node server/services/goal-contract.js run --target <被测产物绝对路径> --run-id <本次 run_id>
```

`--run-dir` / `--node-run-id` / `--attempt` 不给的话会从 `--target` 路径自己推，通常不用填。
需要完整判决 JSON 时加 `--json`。

**退出码就是判决**，别看错：

| 退出码 | 含义 | 你该怎么办 |
|---|---|---|
| `0` | 契约全绿 | 继续 Step 4 的另外两个 pass 条件（task-goal 逐条回扣） |
| `1` | **判决为 fail**（工具是好的） | 照它打印的 `fail_reason` 与 `failures[]` 走 Step 5 |
| `2` | 跑不出判决：没契约 / 契约非法 / 参数错 | = `input_underspecified`，退 `org-planner`。**不是「那就跳过这条」** |

判决已经由执行器落盘到 `artifacts/verdicts/{verdictId}.json`，输出里给了路径。
你的判决 JSON 里贴 `verdict_id` 就够，不用把整份判决抄一遍。

🚨 **不要自己写 `npx vitest run <脚本>` 之类的命令去跑 `goal-test-script`。**
执行器的 `runner` 白名单目前只有 `node`（原因见 `27-goal-contract-format.md` §4.3 的实测结论），
你手拼的命令跑出来的结果**不会**进 `verdicts/`，也就不可追溯——等于没跑。

先看一眼契约里都有哪几段（三段各自可为 null，你只验非 null 的）：

```bash
node server/services/goal-contract.js validate --run-dir $R
node server/services/goal-contract.js list --run-dir $R --limit 10   # 历次判决
```

## 3. 拿归因结论

`validator-triager` 是你 work graph 的第一个节点，由引擎按图调度，**你不需要手动去 call 它**。
它的产出在：

```bash
cat $R/nodes/<validator-triager 的 nodeRunId>/attempt-<n>.json
```

从里面取 `fail_reason` 和 `remediation_note`，**原样**放进你的判决 JSON。

## 4. 写判决

用文件写入工具写：

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

格式见 `agent.md`「产出格式」（`schema: "org-validator/v1"`）。不要覆盖上一次 attempt 的文件。

写完只回一句话：pass/fail + 总分/及格线 + （fail 时）`fail_reason` 和退向哪个 org node。

---

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

| 别用 | 为什么 |
|---|---|
| 任何改代码 / 改 PRD / 补测试的工具 | 你是闸门，不是施工队。发现问题打回去，不许自己顺手补 |
| 往 `artifacts/` 写任何东西 | 写共享区是特权动作，只有被标记为契约产出者的节点才有 |
| 读别的 org node 的 `nodes/{其他}/` 私有目录 | 节点私有产出彼此隔离（§四.A.5），你看契约和交付物，不看人家的过程 |
| `node bin/lemon.js task dispatch` 给 `innovator` / 任何训练类工具 | 判到 `skill_defect` 也只挂起等人工，L4 是 P3 非目标 |
| 直接写 `data/` 下的 sqlite | 三值透传由引擎从你的判决 JSON 里读走并落库 |
| 自己写一份验收标准 | 标准由 `org-planner` 产出、由你执行（R-9.3）。现编标准 = 自己给自己出考题 |