# SDD Planning 工具箱

你的活是四步：**读上游契约 → 勘察现有代码 → 写 SDD → 写回执**。

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

---

## 1. 读上游契约

```bash
R=data/companies/<公司ID>/runs/<rootRunId>
cat $R/artifacts/task-goal.json
cat <提示词给的 prd 节点目录>/contract.json
cat <提示词给的 prd 节点目录>/prd.md
```

上一轮的 `remediation_note` **由引擎在提示词里带给你**。

❌ **提示词没给到路径的节点目录一律不要翻**——节点私有目录彼此隔离（§四.A.5）。
上游没给够，就是 `input_underspecified`，不要自己翻墙去找。

## 2. 勘察现有代码（本岗位的必要动作，**只读**）

设计"新增模块"之前先确认它是不是已经存在。用只读工具：

```bash
# 关键词摸底：要碰的概念在仓库里已经有谁在做
grep -rn "<关键词>" server/ web/ packages/ --include='*.js' --include='*.vue' | head -30

# 目录结构与既有服务清单
ls server/services/ server/routes/

# 读具体文件确认现状（用文件读取工具，不要 cat 大文件）
```

判据：**改哪个现有文件，永远优于新建一个。** 确实要新建时，
在 SDD 里写明"为什么现有的那个不能改"。

⚠️ 勘察阶段**一行代码都不许改**。你在读，不在写。

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

| 文件 | 内容 | 谁读 |
|---|---|---|
| `sdd.md` | SDD 正文 | `goal-benchmark` / `planner-validator` / `org-coder` |
| `contract.json` | `{"exports": {...}}`，见 `agent.md` | **引擎**（算 hash 决定级联）+ 下游节点 |
| `attempt-<n>.json` | 本轮回执，`schema: "work-product/v1"` | **引擎**（判本节点成功/失败） |

目录的绝对路径由引擎在提示词的「节点产物目录」一段里给出。
`<n>` 是本轮 attempt 序号；**不要覆盖上一次 attempt 的文件**。

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

| 别用 | 为什么 |
|---|---|
| 任何**写**代码文件的工具 | 你产出设计，不产出实现。写实现是 `org-coder` 那个 org node 的活 |
| `npm run` / 起服务 / 跑测试 | 你不验证运行时行为；那是 coder 和 validator 的活 |
| `node server/services/goal-contract.js put …` | 写验收契约是 `goal-benchmark` 的特权（`writesArtifacts: true`） |
| 任何写 `$R/artifacts/` 的动作 | 共享产物区对你**只读**（§四.A.5） |
| `node bin/lemon.js task transition` | 阶段流转由**图的边**提供，节点内部不再跑四段式（§九bis） |
| 读提示词没给到的节点目录 | 隔离规则，见上 |
| 直接写 `data/` 下的 sqlite | 状态由引擎从你的 `attempt-<n>.json` 里读走并落库 |