# `runs/` —— 6′ 的 run 记录（spec §5.1）

每个 `runs/<runId>/` 是一次 run 的全部证据：

| 文件 | 是什么 |
|---|---|
| `run.json` | §5.1 全字段元数据（三元组主键 + promptHash + channel + usage + 产物 sha） |
| `transcript.jsonl` | 原始 stream-json（L2 按需加载面的**唯一**证据来源） |
| `context-manifest.json` | `metrics/context-manifest.mjs` 采的 L1+L2（**通道等价判据比的就是它的 `L1Fingerprint`**） |
| `GT-00X.html` | 产物 |
| `final-message.md` | 模型最后一条回复原文（HTML 抽取的输入面） |

---

## 通道等价判据（6′ 起手裁决的落地形态）

spec §5.1 只写「每次 run 必须在**全新会话**、固定 cwd」，**没定义「全新会话」**。
本轮不裁那个词，裁**判据** —— 两个通道对 §5.1 等价，当且仅当：

- **L1（确定性层）逐字段同构**：cwd 事实 + 入口规则文件清单&sha + hook 注入面&sha + harness 声明位齐全
  ⇒ 落地成一个可比对的 `L1Fingerprint`。**1 run/通道即可判定**。
- **L2（随机层）不要求相同**（它本身就是 6′ 要测的方差之一），但要求**结构可比**：
  两通道都得有非空的按需加载面。一个通道压根不发生 `Read` ⇒ 不可比，判**不等价**。

---

## 通道 A：headless（自动，lab 侧跑）

```bash
node adapters/run-golden-task.mjs \
  --task tasks/tvu-ds/v1/gt-001-live-source-console.json \
  --pin ~/.ai-ds-lab/pins/tvu-ds-4a68e02d \
  --channel headless --run-id r00X --model claude-opus-5 --repeat-index X
```

⛔ 每次 run 前必先跑冻结校验：
```bash
node metrics/golden-set-freeze.mjs --pin ~/.ai-ds-lab/pins/tvu-ds-4a68e02d
```

---

## 通道 B：manual（人工，真开一个新 session）

**这条通道存在的理由**：它是 §5.1 字面义下最保真的那个 —— 测的就是设计师真实会遇到的
harness。headless 与它是否等价，正是本轮校准要用数据回答的问题。

### 📋 手把手版（2026-08-25 补 · 本次要跑的是 **r006**）

> 下面这版把「跑完怎么把东西交回来」那一步**去掉了** —— 真人 session 的 transcript 会自动落在
> `~/.claude/projects/-Users-nancy--ai-ds-lab-pins-tvu-ds-4a68e02d/` 下（已实测存在，headless 的四个 run
> 就在那里），lab 侧能自己按 mtime 捞最新那份并抽出最终回复。**你只需要跑，不需要复制粘贴产物。**

**第 1 步 · 开一个 cwd 落在 pin 上的全新 session。** 两条路任选：

- **VSCode**：`File → Open Folder…` 打开 `~/.ai-ds-lab/pins/tvu-ds-4a68e02d`，在那个窗口里新开 Claude Code。
- **终端**：⚠️ PATH 上的 `claude` 是坏的（发现 N41，npm 那份 bin 被挪走且无 +x），**必须用全路径**：
  ```bash
  cd ~/.ai-ds-lab/pins/tvu-ds-4a68e02d
  /Users/nancy/.vscode/extensions/anthropic.claude-code-2.1.241-darwin-arm64/resources/native-binary/claude
  ```

⛔ 不是 DS 真源工作树（`~/Documents/AICoding/VS_Code/tvu-design-system`）。走错 cwd 这次 run 作废。
⛔ 不是 `--continue`、不是 `--resume`、不是本 session、不是 subagent。

**第 2 步 · 确认模型。** 在那个 session 里敲 `/model`，选 **Opus 5**（要与 headless 的 `claude-opus-5` 对齐）。
把它显示的**准确 model id** 记下来告诉 lab —— 那是 §5.2 三元组主键之一，⛔ 不留空、不猜。

**第 3 步 · 粘贴。** 把 [`GT-001.full-prompt.txt`](GT-001.full-prompt.txt) 的**全文**（1,118 字节，含开头
「【执行约束…】」那 4 行）一次性粘进去发送。
⛔ 一个字都别改、别在前后补话、别分两次发 —— 改了 `promptHash` / `harnessPreambleSha` 就对不上，两个通道不可比。

**第 4 步 · 跑的过程中：任何要写文件的请求一律拒绝。**
（`Write` / `Edit` / `Bash` 的权限弹窗全按拒绝。）
⚠️ 这一步是硬约束不是建议：pin 被写一次，**整条基线作废**，前面所有 run 的读数一起废。
lab 会在你说跑完之后核 `git status`，脏了就判这次 run 作废并还原。

**第 5 步 · 跑完了，回来跟 lab 说一声「r006 跑完了，model 是 XXX」。** 就这样，不用复制产物。
lab 会自己做完剩下的：捞 transcript → 抽 ```html 围栏 → 登记 run.json → 采 `contextManifest` → 比 `L1Fingerprint`。

**⚠️ 一件要有心理准备的事**：这条 run 大概要 **16–25 分钟**（headless 实测 16.4 / 19.4 / 24.7 分钟），
中途它会读几十个文件。⛔ 别中途打断它、别插话追加要求 —— 插一句话这次 run 就不是同一个 prompt 了。

---

### 操作步骤（原版，命令行细节）

1. **真开一个全新的 Claude Code session**（不是 subagent、不是 `--continue`、不是本 session）。
2. **cwd 必须是 pin worktree**：
   ```
   ~/.ai-ds-lab/pins/tvu-ds-4a68e02d
   ```
   ⛔ 不是 DS 真源工作树（`~/Documents/AICoding/VS_Code/tvu-design-system`）。走错 cwd 这次 run 作废。
3. **原样粘贴** [`GT-001.full-prompt.txt`](GT-001.full-prompt.txt) 的**全文**（1,118 字节）。
   ⛔ 一个字都别改、别补充说明 —— 改了 `promptHash` 就对不上，两个通道不可比。
4. 那个 session 里**不要让它写任何文件**（问到就拒），产物只看它最后一条回复里的 ```html 围栏。
5. 跑完后回到本 session，把最后一条回复存成一个 `.md` 文件，然后登记：
   ```bash
   node adapters/run-golden-task.mjs \
     --task tasks/tvu-ds/v1/gt-001-live-source-console.json \
     --pin ~/.ai-ds-lab/pins/tvu-ds-4a68e02d \
     --channel manual --run-id r00X --model <那个 session 真实用的 model id> \
     --result-file <刚存的 .md>
   ```

### 校验用的固定值（对不上就是走样了）

| 项 | 值 |
|---|---|
| `promptHash`（冻结正文，⛔ 不含 preamble） | `559c6decc5b4cf58d12e2062aed55810d67367ecca16a9761b019c4275813d14` |
| `harnessPreambleSha` | `b7c1189eebac8db91af5c166a8afe2523190f13513e945a5637d57725b10fb4f` |
| `subjectSha` | `4a68e02d3d695cee3c39d255ea5d20f7f2bf9b8c` |

### ⚠️ 这条通道自带的一处不诚实（如实登记，不是 TODO）

preamble 里逐字写着「Write / Edit / Bash 工具已停用」—— 在 **headless 通道这是真的**
（`--disallowedTools` 强制），在 **manual 通道这是假的**（交互 session 里那些工具还在）。

⇒ 两个通道的**行为契约相同**（都不写文件、都把 HTML 放进围栏），但**这一句的真值不同**。
保持措辞一致是为了让 `harnessPreambleSha` 可比；代价就是 manual 通道里这句话是一句
「模型会照做、但字面不成立」的指令。⛔ 别把它读成两通道完全同质。