# Planner Validator 工具箱

三步：**读产物与标准 → 逐项审 → 写判决**。

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

---

## 1. 读被验产物 + 待审标准

```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                   # 某段写成 {"$ref": ...} 时，内容在外置文件里
```

契约是**一份** `acceptance.json`，三段（`benchmark` / `test_data` / `test_script`）由
`goal-benchmark` / `goal-test-data` / `goal-test-script` 三个节点各写自己那一段。
只 `cat` 外置文件会漏掉内联写的那几段。

规划产物（BRD / PRD / SDD / 任务拆解）的路径由本次调用的提示词给出，**原始需求（task-goal）也在提示词里**。
职责 B 的覆盖率对着 task-goal 数，不对着 PRD 数。

`artifacts/` 只读——往共享区写是产出者的特权动作，不是你的。

## 2. 审标准时的三个实用手法

**a) 先让执行器做一次形状体检**（免得你人肉去数权重和是不是 1）

```bash
node server/services/goal-contract.js validate --run-dir $R
```

退出码：`0` 契约形状合法 / `1` **契约非法**（它会逐条打印 `[rule] detail`）/ `2` 根本没有 `acceptance.json`。

它替你挡掉的是**形状**问题：三段全 null 的空契约（= 平凡通过，§四.D.3 点名的漏洞）、
benchmark 权重之和 ≠ 1、维度名重复、`runner` 不在白名单、`test_script.path` 逃出 `artifacts/`、
`$ref` 指向的文件不存在。**拿到 1 或 2 就直接判 B.3 不过**，把它打印的 `[rule] detail` 原样贴进判决。

⚠️ 反过来不成立：**`validate` 退出 0 只说明形状对，不说明标准写得对**。
「及格线 80 分从哪来」「维度写着『用户体验佳』」「样本只有 happy path」「这条 task-goal 没有任何维度覆盖」
这些机器一条也查不出来——那才是你这一节的活。别拿 `validate` 退出 0 当自己审过了。

🚨 你**只 `validate`，不 `run`**。跑契约判整个任务过没过是 `org-validator` 那一层的活。

**b) 找空断言 / 被跳过的用例**（B.3 的常客，grep 一遍最快）

```bash
grep -rn "toBe(true)\|toBeTruthy()\|\.skip\|\.todo\|expect(1)" $R/artifacts/goal-test-script/ || true
```

**c) 看样本集有没有边界与异常**

```bash
ls $R/artifacts/goal-test-data/
```

只有 `normal*` / `happy*` 一类文件、没有边界（空值 / 极大 / 越界）和异常（非法输入 / 依赖不可用）样本 → B.3 不过。

契约的字段格式与执行器是 `server/services/goal-contract.js`，**格式以它为准，不要自己发明字段**。
你**审**这份标准，不负责**执行**它——执行是 `org-validator` 那一层的活。

## 3. 写判决

用文件写入工具写：

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

格式见 `agent.md`「产出格式」（`schema: "work-validator/v1"`，`validator: "planner-validator"`）。
🚨 `verdict` 只能是 `passed` / `attributed` / `inconclusive`——**写 `pass` / `fail` 引擎读成「没失败」**。
不要覆盖上一次 attempt 的文件。

写完只回一句话：verdict + 哪几项没过 + （判失败时）打回哪个节点。

---

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

| 别用 | 为什么 |
|---|---|
| 任何改 PRD / SDD / 改验收标准的工具 | 你只判不改。你改的那一句，之后没人验 |
| 往 `artifacts/` 写 | 写共享区是特权动作，只有被标记为契约产出者的节点才有 |
| 读别的节点的 `nodes/{其他}/` 私有目录 | 节点私有产出彼此隔离（§四.A.5） |
| 跑 `goal-test-script` 判整个任务过没过 | 那是 org 层 `org-validator` 的活。你审这套脚本本身写得对不对 |
| 给出「整个任务该退回哪个 org node」的结论 | 那是 org 层 `validator-triager` 的活，越权 |
| 训练 / 进化 / retrain 相关的一切 | L4 是 P3 非目标 |