# 过程载体目录说明（`docs/process/tools/`）

> **总规则以流程总纲的「过程载体与脚本约定」一节为准**；本文件只放**编写细则**与**登记区**。
> ⚠ 本目录通常**不进版本库**（被忽略规则排除）⇒ 本文件也一样，会随载体一起被清理；需要时从 git 历史取回（或从可选归档包取回）。
> **什么算过程载体**：验收载体 · 探针 · 夹具播种 / 清理 · 截图 / 取证 · 一次性数据核对 —— 为**某一批**产出的过程件。
> **什么不算**：需长期复跑的正式测试（进 `test/`）与**长期复跑的流程闸门**（进受版本控制的 `scripts/`，否则换台机器即失效）；门禁、journal 追加等常驻流程工具**勿当过程件搬走**。

---

## 编写细则

1. **在仓库根执行**：按扩展名选择运行器（`.ts` / `.mjs` / `.sh` / `.py`）；具体用法以各脚本头部注释为准。
2. ★★ **定位仓库根必须动态找，禁止硬编码相对层数** —— 算错一层的后果不是报错，而是**证据静默写进错目录**（= 证据丢失，比硬失败更难发现）：

```ts
// CJS 可用 __dirname；ESM 可用 dirname(fileURLToPath(import.meta.url))
function findRepoRoot(from: string) {
  let dir = from;
  for (;;) {
    if (existsSync(join(dir, '.git'))) return dir;
    const parent = dirname(dir);
    if (parent === dir) throw new Error(`找不到仓库根：${from}`);
    dir = parent;
  }
}
```

3. ★★ **若运行器把 `.ts` 按 CJS 转译**（报 `Top-level await is currently not supported with the "cjs" output format`）⇒ **禁用 `import.meta.*` 与顶层 `await import()`**；要加载仓库内源码用 `createRequire(__filename)(绝对路径)`。
4. ★★ **必须断言自己的证据落点**：写入前确认目标在约定证据目录之内（PROJECT.md §1 指定的过程产物路径），**不在就 `exit 1` 并打印「解析出的仓库根 + 目标路径」**。落点可由**环境变量覆盖，统一用 `<EVID_DIR_ENV>`**，但**同样受落点断言约束，越界即 `exit 1`**（覆盖 ≠ 后门）。
5. ★★ **回归靠运行证据，不靠版本控制**：本目录通常没有版本控制痕迹 ⇒ 改动的正确性**只能由"跑一遍的读数"背书** ⇒ 动过载体，报告必须附**复跑读数（含反向对照）**。
6. ★★ **清理装置必须自证「清理后残留 = 0」**：各步彼此独立（每步 / 每表各自 `try/catch`，禁止把多条删除写在同一个事务里）；结束时**硬断言残留 = 0**，否则判红；交付必附「跑前 / 跑后」两次读数。
7. **报「绿」必须附「它怎么才会红」**：只落盘、永不非零退出的脚本等同静默免检，不得计入覆盖；反向对照是最低成本的证明。

---

<!-- process:registry -->
## 登记区（勿移 / 待提交）

> **用途**：落点门禁的**唯一放行来源 = 本节**。它只判"会进下一次提交"的**未跟踪**文件。
> **规则**：批次生产迁移 / 运维脚本落 `scripts/<ID>-<用途>.{ts,sql}`；**未提交期间**在**本节末尾加一行**登记（**登记即放行**），**提交后立即删掉该行** —— 本节只留常驻件，不积压批次业务件。
> 已提交的文件**无需登记**（门禁只扫未跟踪文件）。
> **升级备份不必登记**：`process_init(upgrade)` 落在文件旁的 `<文件>.bak-<时间戳>` 由门禁自动排除（临时件），核对无误后直接删。

**常驻（已在版本控制内，勿当过程件搬走）**：

- `<产物落点门禁脚本>` · `<台账门禁脚本>` —— 常驻门禁，已并入「快速验证」命令槽（见 PROJECT.md §2），勿搬走。
- `<journal 追加脚本>` · `<版本同步脚本>` —— 常驻流程工具，勿当过程件搬走。

**批次登记行（示例格式，勿照抄；照抄后必须把 `<...>` 换成真实路径）**：

> 下面代码块只是写法示范，**不构成任何登记**（门禁不解析代码块内部，且含 `<...>` 的条目一律不算登记）。

```markdown
- `scripts/<ID>-<用途>.{ts,sql}` —— 批次数据回填脚本（只读默认 + 打印复原 SQL）；**提交后删掉本行**。
```
