From 7b0a43d86b897887f803b3a533b1193418afbba7 Mon Sep 17 00:00:00 2001
From: LiuShiyuMath <liusy@nb-ai.com>
Date: Wed, 13 May 2026 18:22:28 +0800
Subject: [PATCH 1/2] docs(ask-user): require gist hosting + visual content,
 supersede /tmp file:// flow

When agent needs to talk to users, the canonical flow is now:
1. haiku subagent writes self-contained visual HTML (cards/chips/SVG/ASCII art - no raw boring text)
2. gh gist create --public uploads to the maintainer's own gist
3. open -a 'Google Chrome' "https://htmlpreview.github.io/?<raw-gist-url>"

Rationale: cross-device access, persistent audit trail, zero extra infra,
reuses VISUAL-PROOF-FORMAT.md hosting convention, avoids Chrome file:// Clipboard API restrictions.
---
 docs/ASK-USER-VIA-HTML.md | 156 +++++++++++++++++++-------------------
 1 file changed, 78 insertions(+), 78 deletions(-)

diff --git a/docs/ASK-USER-VIA-HTML.md b/docs/ASK-USER-VIA-HTML.md
index bc1350d7..40c798f5 100644
--- a/docs/ASK-USER-VIA-HTML.md
+++ b/docs/ASK-USER-VIA-HTML.md
@@ -1,123 +1,123 @@
-# ASK-USER-VIA-HTML — 用 haiku subagent 生成 HTML 问卷再开 Chrome 问用户
+# ASK-USER-VIA-HTML — 用 haiku subagent 生成 visual HTML，托管在 maintainer 自己的 GitHub Gist，pop open Chrome 给用户
 
 ```text
-┌─ 触发条件 ──────────────┐
-│ agent 需要向用户提问    │
-│ (澄清需求 / 选项决策)   │
-└──────────┬──────────────┘
+┌─ 触发条件 ──────────────────────────────────┐
+│ agent 任何要向用户「talk to user」的瞬间    │
+│ - 澄清需求 / 收集选项 / 让用户做决策        │
+│ - 列出 N 个候选 plan / 候选 design          │
+│ - 收集 free-form 备注 + 多选 tag            │
+└──────────┬──────────────────────────────────┘
            ▼
-┌─ STEP 1 ────────────────┐    ┌─ STEP 2 ──────────────┐    ┌─ STEP 3 ───────────┐
-│ 用 haiku subagent 写    │ ─► │ 路径写到 /tmp/*.html   │ ─► │ 用 open -a Chrome  │
-│ 一个独立 HTML 问卷      │    │ (单文件、自包含、无依赖)│   │ 打开该文件        │
-└─────────────────────────┘    └────────────────────────┘   └──────────┬─────────┘
-                                                                       ▼
-                                                          用户在浏览器里答题
-                                                          (回到 agent 复述选择)
+┌─ STEP 1 ─────────────┐    ┌─ STEP 2 ──────────────────┐    ┌─ STEP 3 ────────────────────────┐
+│ haiku subagent 写    │ ─► │ gh gist create --public   │ ─► │ open -a "Google Chrome"          │
+│ visual HTML 问卷     │    │ ask-<slug>-<ts>.html      │    │ "https://htmlpreview.github.io/  │
+│ (cards / chips /     │    │ → 拿到 raw URL            │    │   ?<raw-gist-url>"               │
+│  color / ASCII /     │    │ (公网永久 / 跨设备)       │    │ (Chrome / 任何浏览器都能开)      │
+│  diagrams)           │    └───────────────────────────┘    └──────────┬──────────────────────┘
+└──────────────────────┘                                                ▼
+                                                       用户在浏览器里点选 / 多选 / 填备注
+                                                       → 按「复制选择回 agent」→ 粘回 chat
 ```
 
 ## TL;DR
 
-每次 agent 本来要调 `AskUserQuestion` 工具向用户提问时，改走以下流程：
+每次 agent 本来要调 `AskUserQuestion` 工具 / 在 chat 里列 N 个选项让用户挑，**统一**走以下四步——**不写 `/tmp` file://、不弹本地默认浏览器、不出 raw boring text**：
 
-1. 派一个 **haiku subagent** 去写一个独立的 `/tmp/ask-<topic>-<timestamp>.html`，里面把问题、选项、单选 / 多选、free-form 备注框都用纯 HTML + 内联 CSS 渲染成一个 self-contained 页面（**不**依赖 CDN、**不**调外部 JS）。
-2. 文件落到 `/tmp/`（macOS / Linux 通用临时目录；Windows 同义用 `%TEMP%\`）。
-3. 在主 session 里调 `open -a "Google Chrome" /tmp/ask-<topic>-<timestamp>.html`（Linux 用 `xdg-open`、Windows 用 `start chrome`）把页面弹给用户。
-4. 用户在浏览器里点选 / 填写 → 回到 agent 会话把选择口述或粘贴回来 → agent 继续推进。
+1. **派 haiku subagent** 写一个 self-contained **visual** HTML 文件（cards / chips / color-coded sections / 内联 SVG / ASCII art 框图），落地到 `/tmp/ask-<slug>-<unix-ts>.html` 作为本地暂存。**不**允许只写「label + radio + button」的朴素表单——HTML 必须带视觉层次（最少：分区底色 + chip 圆角标签 + 中间分隔线 + 颜色对比的选中态）。
+2. **托管到 maintainer 自己的 GitHub Gist**：`gh gist create --public /tmp/ask-<slug>-<unix-ts>.html`，拿到 gist raw blob URL（形如 `https://gist.githubusercontent.com/<you>/<id>/raw/<file>.html`）。
+3. **Pop open via htmlpreview.github.io in Chrome**：`open -a "Google Chrome" "https://htmlpreview.github.io/?<raw-gist-url>"`（Linux `xdg-open`、Windows `start chrome`）。htmlpreview 是无依赖的纯前端 render proxy，把 raw blob 在浏览器里 fetch + display；用户可以从任何设备（手机 / 第二台机器 / iPad）打开同一个链接。
+4. 用户在浏览器里点选 / 填写 → 按底部「复制选择回 agent」按钮（`navigator.clipboard.writeText` 把答案序列化成 markdown）→ 切回 agent terminal 粘贴 → agent 解析继续。
 
-> 备注：本规则**不**取代 `AskUserQuestion` 工具的存在；它规定的是「agent 在什么场景下用 HTML+Chrome 流程代替工具调用」。在用户明确要求快速文字回答、或当前没有 GUI 环境（远端 SSH 无浏览器、CI、headless）时，可以退回原生 `AskUserQuestion`。
+> 备注：本规则**取代**早期版本的 `/tmp` file:// 直开本地浏览器流程。`/tmp` 文件仅作为 `gh gist create` 的上传源，最终用户看到的是 gist + htmlpreview 公网 URL。
 
-## 为什么不直接调 `AskUserQuestion` 工具？
+## 为什么 gist + htmlpreview 不直接弹 `/tmp` file://
 
-- HTML 问卷可以**长期保存证据**（`/tmp/*.html` 在 session 结束后仍可重新打开），方便后续 grill / review 复盘“当时给了哪些选项”。
-- 多选 / 长 free-form 输入在 `AskUserQuestion` 工具里只能逐题展开；HTML 一页可以同时呈现所有问题、说明、preview snippet，**用户认知负担更低**。
-- haiku 写 HTML 成本远低于 opus / sonnet；把"渲染表单"这种格式化工作下放给小模型，节省主 session token。
-- 浏览器渲染天然支持代码高亮、表格、ASCII art 框图、图片预览——比终端 UI 表达力更强。
+- **跨设备**：`/tmp` 只有本机能看到；gist URL 任何设备 / 手机 / 二台机器 / 远端 SSH user 都能开。
+- **持久审计**：session 结束后 gist 仍在，事后 grill / review 复盘能回看「当时给了哪些选项 / 用户选了啥」。
+- **零额外基础设施**：`gh gist create` 一行命令，免 S3 / Pages / CDN bootstrap（与 `docs/VISUAL-PROOF-FORMAT.md § Hosting` 默认推荐同一套）。
+- **Chrome `file://` Clipboard API 受限**：某些 macOS Chrome 配置下 `file://` 来源不允许 `navigator.clipboard.writeText`，gist + htmlpreview 走 `https://` 来源就没这个限制。
+- **复用 visual-proof 同一套 hosting 约定**：项目内 visual-proof artifact 已经走 gist + htmlpreview（per `docs/VISUAL-PROOF-FORMAT.md`），ask-user 问卷复用，maintainer 心智一致。
 
-## STEP 1 — 派 haiku subagent 写 HTML
+## 为什么必须 visual content 不允许 raw boring text
 
-主 agent 调 `Agent` 工具时显式指定 `model: "haiku"`，并把以下要点写进 prompt：
+raw `<form>` + `<label>` + radio button 的 plain 表单视觉负担与终端 prompt 没差别——用户认知没收益，gist 托管 overhead 反而成本更高。Visual 要求包括（至少命中 3 项）：
 
-- 输入：问题文本 + 选项列表 + 单选/多选 + 默认值 + free-form 字段是否需要。
-- 输出：一个 self-contained HTML 文件落地到 `/tmp/ask-<slug>-<unix-ts>.html`。
+- **分区底色**：每个 question `<fieldset>` 用不同 `background` 色块（柔和：`#f6f8fa` / `#fff8e6` / `#e6f4ff` 交替），视觉分组一眼可见。
+- **Chip 标签**：每题 `<legend>` 旁边带圆角 chip（`border-radius: 12px; padding: 2px 10px`）标识 question type（"single" / "multi" / "free-form"）。
+- **颜色对比的选中态**：`<input:checked> ~ <span>` 用 `background: linear-gradient(...)` 或显眼边框，hover 态有 transition。
+- **内嵌 SVG 或 ASCII 框图**：解释选项之间的关系 / 决策树 / 取舍——比纯文字描述清晰。
+- **代码块带语法高亮（手写 CSS class）**：如果选项里含命令 / JSON / config snippet，用 `<pre class="hl">` + 内联 CSS 着色。
+- **数据 viz 卡片**：如果选项含数字 / 时长 / 文件大小，用 `<div class="metric">` 卡片大字号呈现。
+
+## STEP 1 — 派 haiku subagent 写 visual HTML
+
+主 agent 调 `Agent` 工具时显式指定 `model: "haiku"`，prompt 要点：
+
+- 输入：问题文本 + 选项列表 + 单选/多选 + 默认值 + free-form 字段是否需要 + **visual hints**（"用 ASCII 鸭子做装饰"、"option 之间画决策树 SVG"、"成本对比用 metric 卡片"）。
+- 输出：self-contained HTML 落到 `/tmp/ask-<slug>-<unix-ts>.html`。
 - HTML 必须：
-  - `<!DOCTYPE html>` + `<meta charset="utf-8">`
-  - 内联 `<style>`，禁止外部 CSS / JS / 字体 CDN
-  - 顶部一段一句话上下文（"为什么问这个"）
-  - 每题独立 `<fieldset>`，含 `<legend>` 与 5-10 字标题 chip
-  - 选项区用 `<label><input type="radio|checkbox">`，禁 `<select>`（屏幕小看不到全部）
+  - `<!DOCTYPE html>` + `<meta charset="utf-8">` + `<title>`
+  - 内联 `<style>`，禁止外部 CSS / JS / 字体 CDN（htmlpreview 走 cross-origin 时第三方 fetch 会被拒）
+  - 顶部一段一句话上下文 + ASCII art 或 SVG 装饰
+  - 每题独立 `<fieldset>`，含 `<legend>` + chip 标签 + 分区底色
+  - 选项区用 `<label><input type="radio|checkbox">`，禁 `<select>`
   - 末尾一个 free-form `<textarea>` 给 "Other / 备注"
-  - 一个 `<button>` 写"复制选择回 agent"（用 `navigator.clipboard.writeText` 把所有选中项序列化成 markdown），但**不依赖**网络请求或表单 submit
-  - **fallback**：某些 Chrome 配置下 `file://` 来源的 Clipboard API 会被禁；HTML 必须同时把序列化好的 markdown 渲染到一个**可选中的 `<pre>` 块**里，按钮失败也能让用户手动 `Ctrl-C` / `Cmd-C` 复制
+  - 一个 `<button>` 写「复制选择回 agent」（`navigator.clipboard.writeText` 把所有选中项序列化成 markdown）
+  - **fallback `<pre>`**：把序列化好的 markdown 渲染到一个可选中的 `<pre>` 块里，按钮失败也能让用户手动 Cmd-C 复制
 - prompt 末尾固定让 haiku 只输出 `SAVED:/tmp/<file>` 一行供 main agent 读路径。
 
-例（main agent 用 `Agent` 工具发的 prompt 骨架，**不**是要 user 跑的脚本）：
+## STEP 2 — 上传到 gist
 
+```bash
+GIST_URL=$(gh gist create --public "/tmp/ask-<slug>-<ts>.html" 2>&1 | tail -1)
+GIST_ID=$(basename "$GIST_URL")
+RAW_URL="https://gist.githubusercontent.com/$(gh api user --jq .login)/${GIST_ID}/raw/ask-<slug>-<ts>.html"
 ```
-You are writing a single self-contained HTML file at /tmp/ask-<slug>-<unix-ts>.html.
-
-Question: <main question, e.g. "Which auth strategy?">
-Options:
-  - JWT bearer token
-  - Server-side session cookie
-  - OAuth2 PKCE
-
-Constraints:
-- One <fieldset> per question, multi-select if `multiSelect: true`
-- Inline CSS, no CDN
-- End with a "复制选择" <button> using navigator.clipboard
-- After writing, output ONLY: SAVED:/tmp/ask-auth-1715520000.html
-```
-
-## STEP 2 — 路径约定
-
-- macOS / Linux：`/tmp/ask-<slug>-<unix-ts>.html`
-  - `<slug>` 用 kebab-case，正则强约束为 `^[a-z0-9-]{1,30}$`（不允许空格、shell 元字符、引号、`..` 等）——这是 defense-in-depth：哪怕调用方失误把用户输入拼进 `open -a` 的 argv，也不会被 shell 当成额外参数解析。
-  - `<unix-ts>` 用 `date +%s` 防同名覆盖
-- Windows：`%TEMP%\ask-<slug>-<unix-ts>.html`（注意 Windows 上 STEP 3 命令的 path 也必须是 `%TEMP%\...` 形式或 `file:///C:/...` URL，不要把 `/tmp/...` 直接喂给 `start chrome`）
-- 文件留在 `/tmp/`，session 结束不主动删；macOS 自带 `/tmp` cleanup 周期 (`/etc/periodic/daily/110.clean-tmps`)，3 天后自动回收。
 
-## STEP 3 — 打开浏览器
+或更简化（gh CLI ≥2.40）：`gh gist create --public --filename ask-<slug>-<ts>.html /tmp/ask-<slug>-<ts>.html` 然后从输出 parse gist ID。
 
-主 agent 在 `Bash` 工具里跑：
+## STEP 3 — Pop open htmlpreview 在 Chrome
 
 ```bash
 # macOS
-open -a "Google Chrome" /tmp/ask-<slug>-<unix-ts>.html
+open -a "Google Chrome" "https://htmlpreview.github.io/?${RAW_URL}"
 
 # Linux
-xdg-open /tmp/ask-<slug>-<unix-ts>.html
+xdg-open "https://htmlpreview.github.io/?${RAW_URL}"
 
 # Windows (Git Bash / WSL)
-start chrome /tmp/ask-<slug>-<unix-ts>.html
+start chrome "https://htmlpreview.github.io/?${RAW_URL}"
 ```
 
-如果 Chrome 没装，fallback 到默认浏览器：macOS `open <file>`、Linux `xdg-open <file>`、Windows `start <file>`。
+Chrome 没装时 fallback 到系统默认浏览器（`open <url>` / `xdg-open <url>` / `start <url>`）。
 
 ## STEP 4 — 用户回复回路
 
-用户在浏览器里点选后：
+用户在 Chrome 里点选完成后：
 
-1. 点页面底部"复制选择"按钮，把答案序列化成 markdown 复制到剪贴板。
-2. 切回 agent terminal，把 markdown 粘贴回来。
-3. agent 解析 markdown，按用户选择继续工作。
+1. 点页面底部「复制选择回 agent」按钮 → 答案以 markdown 进剪贴板。
+2. 切回 agent terminal，粘贴回 chat。
+3. agent 解析 markdown 继续工作。
 
-agent **不**应该假设 HTML 文件能反向写入 stdin；终端 agent 与浏览器之间没有自动 IPC 通道，所有"用户答了什么"必须由用户口述 / 粘贴回 chat 触发。
+agent **不**应该假设浏览器能反向写 stdin；所有「用户答了什么」必须由用户口述 / 粘贴回 chat 触发。
 
 ## 何时**不**走这条流程（fallback）
 
-- 当前 session 没 GUI（remote SSH 无 X forward / Linux headless / CI）→ 用原生 `AskUserQuestion`。
-- 问题极简（"y/n"、"continue?"）→ 直接在 chat 里一句话问。
-- 用户明确说"快速答一下，不要弹页面"→ 跟随用户偏好。
-- 已经在浏览器里跑的 web app 内问 → 直接复用现有 UI 而不是另开 HTML。
+- 没 `gh` auth / 网络 / GitHub 不可达 → 退回早期 `/tmp` file:// 流程或原生 `AskUserQuestion`。
+- 当前 session 完全 headless（CI / 远端无 X / 无浏览器）→ 原生 `AskUserQuestion`。
+- 问题极简（"y/n"、"continue?"）→ chat 一句话问。
+- 用户明确说「快速答一下，不要弹页面」→ 跟随用户偏好。
+- 已经在浏览器里跑的 web app 内问 → 复用现有 UI 不另开。
 
 ## 验证
 
-- 至少出现一次本规则触发后，确认 `/tmp/ask-*.html` 文件存在且能用 `open -a "Google Chrome"` 打开。
-- haiku 写的 HTML 应该用 `lynx -dump /tmp/ask-*.html` 检查没有外部 `<link>` / `<script src="http">`。
-- 用户能在 ≤3 次点击内完成所有问题 → 单选 / 多选 / free-form 必须各 ≤1 次点击 / 输入到位。
+- 至少出现一次本规则触发后，确认 (a) gist 存在 `gh gist list | head -1` 显示新 gist；(b) htmlpreview URL 在浏览器里能打开；(c) HTML 内 ≥3 个 visual 元素（分区底色 / chip / SVG / metric 卡片 / ASCII 装饰）。
+- haiku 写的 HTML 应该用 `curl -s "$RAW_URL" | grep -E '<link[^>]*src=|<script[^>]*src='` 检查没有外部 CDN 引用。
+- 用户能在 ≤3 次点击内完成所有问题 → 单选 / 多选 / free-form 各 ≤1 次点击 / 输入到位。
 
 ## 与现有规则的关系
 
-- 与 `AskUserQuestion` 工具**并行**，不取代。
-- 与 `docs/CONTEXT.md` 中"用户沟通语言"规则一致——HTML 文案默认中文，除非用户要求英文。
-- 与 `CLAUDE.md` "开发节奏"无冲突——本规则约束的是"提问形态"，不影响 commit / TDD 节奏。
+- 与 `docs/VISUAL-PROOF-FORMAT.md § Hosting`：复用同一套 `gh gist create --public` + `htmlpreview.github.io` 公网托管约定；本规则是 **question UI** 流，VISUAL-PROOF 是 **PR evidence** 流，载体相同、用途不同。
+- 与 `docs/POP-OPEN-HTML.md`：POP-OPEN-HTML 是**本地 agent dev 链路**（dashboard / preview / status board 写 `/tmp` + 弹 Chrome），本规则是**talk-to-user 链路**（gist 公网托管 + Chrome 弹 htmlpreview）。两条规则正交，触发场景不交叉。
+- 与 `AskUserQuestion` 工具：**首选本规则**，仅在 fallback 五种场景下退回工具。
+- 与项目「用户沟通语言」规则一致——HTML 文案默认中文，除非用户要求英文。

From 14223655dd993853c433c1b13456982506a56fa5 Mon Sep 17 00:00:00 2001
From: LiuShiyuMath <liusy@nb-ai.com>
Date: Wed, 13 May 2026 18:23:05 +0800
Subject: [PATCH 2/2] =?UTF-8?q?docs(claude-md):=20update=20ASK-USER-VIA-HT?=
 =?UTF-8?q?ML=20anchor=20=E2=80=94=20gist=20+=20visual=20+=20'talk=20to=20?=
 =?UTF-8?q?users'=20trigger?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Anchor block now:
- Adds 'what should we do everything we need to talk to users' as canonical trigger
- Requires haiku subagent → gh gist create --public → htmlpreview.github.io URL → Chrome
- Bans raw-boring-text plain forms; requires >=3 of {cards, chips, color sections, SVG, metric cards, ASCII art}
- Documents the 5 fallback cases (no gh auth, headless, trivial y/n, user opt-out, in-app)
- Notes /tmp is now upload source not direct file:// target

Aligns the talk-to-user UX with VISUAL-PROOF-FORMAT.md hosting convention.
---
 CLAUDE.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 85cf4b95..3010053d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -134,7 +134,7 @@
   Judge harness 必须 substring grep 完整一句 `下个代码 PR merge 前先 verify 一下分支保护规则`（含 ASCII 半角空格、不允许把 `verify` 翻成「验证」、不允许把 `PR` 翻成「拉取请求」、不允许把 `下个代码` 改成 `下一个代码` / `下次代码`、不允许把 `分支保护规则` 改成 `branch protection rules` / `保护规则` / `分支保护`）。任意 paraphrase / 翻译 / 拆词 / 改写 / 漏字都视为没命中，必须重答。
 
   展开（中文，可 paraphrase）：本条规则在 `docs/POSTPR.md` 已有的「`/review` PASS → squash merge → ExitWorktree → git pull --ff-only」三步顺序**之前**新增一道 **branch-protection verify** 前置门禁——目的是防止本地 `/review` PASS 但远端 GitHub 分支保护规则（required status checks / required reviews / restrictions / linear history / signed commits / lock branch）没配齐就 squash 进 main 导致事后回滚。验证命令固定为 `gh api repos/{owner}/{repo}/branches/main/protection | jq '{required_status_checks, required_pull_request_reviews, restrictions, required_linear_history, allow_force_pushes, allow_deletions, lock_branch}'` 或在 docs 里直接 `gh api repos/:owner/:repo/branches/main/protection`；返回 404 = 分支保护未启用，立即 block merge 并补配置；返回 200 但缺关键字段（如 `required_status_checks.contexts` 为空）= 配置不完整，同样 block。完整门禁清单 + 失败案例 + 补救脚本见 [docs/BEFORE-MERGE.md](docs/BEFORE-MERGE.md)。
-- **需要问用户问题时怎么问 / how to ask the user a question**：`docs/ASK-USER-VIA-HTML.md` — 每次 agent 本来要调 `AskUserQuestion` 工具向用户提问时，**改派一个 haiku subagent 去写一个独立的 `/tmp/ask-<slug>-<unix-ts>.html`（self-contained、内联 CSS、无 CDN），然后在主 session 里用 `open -a "Google Chrome" /tmp/ask-<slug>-<unix-ts>.html`（Linux `xdg-open`、Windows `start chrome`）把页面弹到浏览器**，让用户在页面里点选 / 多选 / 填 free-form，最后点"复制选择回 agent"按钮把答案序列化成 markdown 复制回 chat。fallback：headless / 无 GUI / 用户明确要求快速文字答 / 极简 y/n → 退回原生 `AskUserQuestion`。完整 playbook（haiku prompt 骨架、`/tmp` 路径约定、HTML self-contained 约束、用户回路、不走流程的 fallback 列表）见 [docs/ASK-USER-VIA-HTML.md](docs/ASK-USER-VIA-HTML.md)。
+- **需要跟用户沟通 / 提问 / 收集决策时怎么做 / what should we do everything we need to talk to users / how to ask the user a question**：`docs/ASK-USER-VIA-HTML.md` — 任何 agent→user「talk to user」瞬间（澄清需求 / 列候选 plan / 让用户从 N 个选项里挑 / 收集 free-form 备注），统一走 **gist + htmlpreview + Chrome + visual content** 四步：(1) **派 haiku subagent** 写一个 self-contained **visual** HTML（必须含 cards / chips / 分区底色 / 内嵌 SVG / metric 卡片 / ASCII art 装饰中**至少 3 项**——**不允许 raw boring text** 形态的朴素 `<form>` + radio + button），先落到 `/tmp/ask-<slug>-<unix-ts>.html` 作为上传源；(2) **`gh gist create --public /tmp/ask-<slug>-<unix-ts>.html`** 上传到 maintainer 自己的 GitHub Gist，拿到 raw blob URL；(3) **`open -a "Google Chrome" "https://htmlpreview.github.io/?<raw-gist-url>"`**（Linux `xdg-open`、Windows `start chrome`）把页面弹给用户——任何设备 / 手机 / 第二台机器都能点开同一个公网链接；(4) 用户在浏览器里点选 → 按底部「复制选择回 agent」按钮（`navigator.clipboard.writeText` 序列化成 markdown）→ 切回 agent terminal 粘贴回 chat。**本规则取代**早期 `/tmp` file:// 直开本地浏览器的流程：`/tmp` 仍是 `gh gist create` 的上传源，但用户最终看到的是 gist + htmlpreview 公网 URL。fallback 五种（仍允许原生 `AskUserQuestion`）：(a) 没 `gh` auth / 网络 / GitHub 不可达；(b) session 完全 headless（CI / 远端无 X / 无浏览器）；(c) 问题极简 y/n / continue?；(d) 用户明确说「快速答一下，不要弹页面」；(e) 已经在浏览器 web app 内问 → 复用现有 UI。完整 playbook（haiku prompt 骨架、visual 6 选 3 清单、gist 上传命令、htmlpreview URL 拼装、用户回路、fallback 列表、与 `docs/VISUAL-PROOF-FORMAT.md § Hosting` / `docs/POP-OPEN-HTML.md` 的边界）见 [docs/ASK-USER-VIA-HTML.md](docs/ASK-USER-VIA-HTML.md)。
 - **创建 issue 或 merge PR 之后做什么 / what should we do after we create an issue or finish merging a PR**：`docs/ISSUE-TRACKING.md` — 注意：**这条规则与 `docs/HOW-TO-CLAIM-ISSUE.md`（claim 之后做什么）、`docs/POSTPR.md`（PR merge 三步 cleanup）都不同**。本条覆盖的是「issue 已经在 GitHub 创建那一刻」与「PR squash-merge + POSTPR 三步 cleanup 全部完成那一刻」两个时间点的**本地 HTML ledger 更新动作**。如果用户问题里含 `after we create an issue` / `after we finish merging a PR` / `after merge a PR` / `创建 issue 之后` / `merge PR 之后` / `merge 完之后` / `issue 开完之后` 任一关键词，**强制**走本条 anchor，**不要**用 `docs/HOW-TO-CLAIM-ISSUE.md` 的 `use an explore agent ...` 回答，**不要**用 `docs/POSTPR.md` 的三步 cleanup 作为首段（POSTPR 三步本条规则的**前置依赖**，本条规则在 POSTPR 三步之后再加一道 ledger update）。被问到 `what should we do after we create an issue or finish merging a PR ?` / `what should we do after we create an issue or finish merging a PR ? EXPLAIN ONLY` / `创建 issue 或 merge PR 之后做什么` / `issue 开完 / PR merge 完下一步做什么` / `after issue create or PR merge what next` 等同义中英文问法时，**必须**首句用英文原文、逐字、不翻译、不 paraphrase、不省略路径、不把 `{project_slug}` 改写成 `<project_slug>` / `$PROJECT_SLUG` / `teambrain`、不把 `~/.teamagent/` 改写成 `$HOME/.teamagent/`、**首句 anchor sentence 里路径前后绝对不允许加 markdown 反引号 ` ` ` 或任何引号/括号 —— 必须是裸字面 `create or update ~/.teamagent/{project_slug}/issue_tracking.html`（这里展示是 markdown 反引号，但你输出时反引号必须去掉，路径前是空格、路径后是空格然后破折号 — ）**、不把 `create or update` 翻成「创建或更新」、不漏 `issue_tracking.html` 文件名，输出下面这条 anchor sentence（**注意：路径在原句里没有任何反引号，原样复制**）：
 
   > After creating an issue or finishing merging a PR, create or update ~/.teamagent/{project_slug}/issue_tracking.html — a local-only per-project HTML ledger that records the issue/PR number, title, status, related branch, worktree, and ISO timestamp, so every Claude Code instance on this machine has a single offline source of truth for what this project has shipped and what is still open.