# BRD Planning 工具箱

你的活只有三步：**读需求 → 写 BRD → 写回执**。工具用得越少越好。

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

---

## 1. 读需求（两处）

```bash
R=data/companies/<公司ID>/runs/<rootRunId>

# a) 原始 task-goal：用户那句自然语言的落盘副本
cat $R/artifacts/task-goal.json

# b) 共享产物区里还有什么（只读）
ls $R/artifacts/
```

上一轮的 `remediation_note` **由引擎在提示词里带给你**，不需要你去查。

❌ **不要读** `$R/nodes/<别的 nodeRunId>/`——节点私有目录彼此隔离
（[27-P3/P4](../../../../../docs/done/system-design/27-p3-p4-work-graph-console.md) §四.A.5）。
你是规划链第一环，本来也没有上游产物可读。

## 2. 写三份产出（全部在你自己的目录里）

```bash
D=data/companies/<公司ID>/runs/<rootRunId>/nodes/<你的 nodeRunId>
ls $D            # 确认目录，引擎已在提示词的「节点产物目录」一段里给了绝对路径
```

用文件写入工具写：

| 文件 | 内容 | 谁读 |
|---|---|---|
| `$D/brd.md` | BRD 正文 | `prd-planning` / `planner-validator` / 人 |
| `$D/contract.json` | `{"exports": {...}}`，见 `agent.md` | **引擎**（算 hash 决定要不要级联作废下游）+ 下游节点 |
| `$D/attempt-<n>.json` | 本轮回执，`schema: "work-product/v1"` | **引擎**（判本节点成功/失败） |

`<n>` 用本节点当前的 attempt 序号（提示词里给了）。
**不要覆盖上一次 attempt 的文件**——规划的演进过程要可审计。

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

| 别用 | 为什么 |
|---|---|
| 写代码 / 建工程目录的一切 | 你产出的是文档，不是产物。写代码是 `org-coder` 那个 org node 的活 |
| `node server/services/goal-contract.js put …` | 写验收契约是 `goal-benchmark` 那个节点的特权（`writesArtifacts: true`），不是你的 |
| 任何写 `$R/artifacts/` 的动作 | 共享产物区对你**只读**（§四.A.5） |
| `node bin/lemon.js task transition` | 阶段流转由**图的边**提供，节点内部不再跑一遍四段式（§九bis） |
| 读别的节点的 `nodes/{其它}/` | 隔离规则，见上 |
| 直接写 `data/` 下的 sqlite | 状态由引擎从你的 `attempt-<n>.json` 里读走并落库 |