AAStarCommunity · jhfnetboy · Aug 5, 2026 · Aug 5, 2026
@@ -0,0 +1,15 @@
+# pilot 配置 — Brood
+#
+# 注意 integration_branch = main：Brood 是单主干仓库，没有 preview 集成分支。
+# pilot 的默认值是 preview，那对本仓库是错的。合并走
+# `git-guard.sh merge-pr <n> --integration main --allow-trunk`，
+# 该 flag 不是绕过：它仍要求分支保护要求审批、且该 PR 已 APPROVED。
+base_branch: main
+integration_branch: main
+protect_patterns: [release, hotfix, cla-signatures]
+remote: origin
+allow_remote_cleanup: false
+docs_dir: docs/agent
+
+# 不设 preflight：preflight.sh 会自动发现 scripts/ci/*.{sh,py} 与 package.json 的 build，
+# 那已经覆盖本仓库全部检查。显式写一条只会让同一个检查跑两遍。
@@ -0,0 +1,37 @@
+# Brood Acceptance — 用户视角「算不算做好了」
+
+> Brood 有两类使用者，验收标准完全不同。混着谈会得出错误结论。
+
+## 使用者一：读进度的人（BroodBrain 站点）
+
+**他要的**：打开站点就知道 Mycelium 生态各仓库在做什么、到哪一步了。
+
+算做好了：
+
+1. `pnpm run build` 成功，`dist/` 里 `index.html` 与 `api/tasks.json` 都非空
+2. 站点是**纯静态**的：无后端、无写接口；任何写操作被拦截并给出中文提示
+3. `dist/` 与源码**可复现**——CI 的 `dist/ matches a fresh build` 为绿
+   （时钟派生字段除外，见 `.github/workflows/verify.yml` 里的说明）
+4. 任务 YAML 全部可解析（CI 的 `Task frontmatter is valid YAML`）——
+   历史上一个未加引号的 `:` 曾让 10 个任务变成空记录进了公开搜索索引
+
+## 使用者二：用 pilot 的开发者（本仓库分发的 skill）
+
+**他要的**：装上 pilot 之后，仓库里的危险动作被拦住，而且拦得住的东西是**真拦得住**。
+
+算做好了：
+
+1. **护栏真的能跑**——不是「代码看起来对」。判据是**用一次**：
+   `git-guard.sh` 的 add/push/pr-create/merge-pr 四条路径、`preflight` 戳记、
+   `grade-change` 定级、`safe-cleanup` 清理，每条都在真实仓库跑通过至少一次
+2. **fail-closed**：查不到证据时拒绝，而不是放行。且「查不了」与「没有」在输出上**必须可区分**
+3. **文档与脚本不脱节**：`reference/*.md` 与 `scripts/*.sh` 零悬空引用；
+   放宽任何一条承诺时，README / SKILL.md / reference 三处同步改
+4. **版本一致**：`plugin.json` 与 `SKILL.md` 声明同一个版本（CI 的 `pilot version matches in both files`）
+
+## 已知未达标项（不掩盖）
+
+- **三阶段主流程（status / plan / run / doctor）从未端到端跑过。** 脚本层验证充分，
+  整机未验证。本文件所在的 `docs/agent/` 就是为了让 `run` 能起跑而补的。
+- **SKILL.md 自称的「首要强制手段」PreToolUse hook 不存在**（TASK-40 仍是 To Do）。
+  现在真正兜底的只有 GitHub 分支保护，它管 PR 合并，**管不到 `git add -A` 和直推**。
@@ -0,0 +1,48 @@
+# Brood Architecture — 技术骨架与不可破边界
+
+## 两个产物，一个仓库
+
+| 产物 | 是什么 | 入口 |
+|:---|:---|:---|
+| **BroodBrain 站点** | 只读静态 SPA + JSON API，发布 Mycelium 生态进度 | `scripts/export-backlog.js` → `dist/` |
+| **pilot skill** | 可安装的仓库级开发操作系统 | `plugins/pilot/skills/pilot/` |
+
+两者共用 `backlog/`（前者展示它，后者不碰它）。
+
+## 站点侧：本地构建，直推产物
+
+```
+backlog/*.md ──(backlog.md CLI :8422)──> export-backlog.js ──> dist/ ──(git)──> GitHub Pages / CF
+```
+
+**不可破的边界：**
+
+1. **`dist/` 入库，CI 不构建。** 部署原样上传 `dist/`。所以「改了内容没重新 build」
+   等于发布了旧站点——这正是 `dist/ matches a fresh build` 守卫存在的原因。
+2. **导出产物必须可复现。** 任何随机/时钟/机器相关的东西都要在
+   `sanitizeApiPayload()` 里清洗掉（绝对路径、mtime），清洗不掉的（如任务平均年龄）
+   在比对前归一化，**而不是从 payload 里删掉**——删了会让线上站点少一个真实数字。
+3. **只读**。注入的拦截脚本挡住所有写方法，并把 `/api/` 请求补 `.json` 后缀。
+
+## pilot 侧：分层强制
+
+```
+① GitHub 分支保护（服务端，不可绕）  ← 唯一真正的机械保证
+② PreToolUse hook（TASK-40，未建）   ← SKILL.md 自称的首要手段，目前为空
+③ git-guard.sh / safe-cleanup.sh    ← best-effort 便利包装 + 纵深防御
+④ SKILL.md 的散文约束               ← 靠模型自觉
+```
+
+**边界：越往下越不可信。** 任何「这条护栏保证了 X」的说法，必须能指到 ① 或 ③ 的
+具体代码行；指不到就只是 ④。今天三个「守卫跑不起来」的教训都出在把 ③ 当成 ① 来信。
+
+**放权必须先建立证据。** `--allow-trunk` 放松「合到哪里」但要求服务端证明分支保护要求审批；
+`--squash-merged` 放松 `-D` 但要求 GitHub 证明某个已合并 PR 引入了该 commit。
+**先证据、后放权**，不是「为了让守卫能跑就削弱它」。
+
+## 外部依赖：只按契约，不 import
+
+- **PR 评审**：外部服务，契约见 `reference/review-contract.md`。pilot 不启动、不感知后端。
+- **文档源（飞书 / Notion）**：契约见 `reference/doc-sources.md`。运行时只探测，不 import。
+
+这条边界是花了 6 轮评审从一次 daemon 硬耦合里拆出来的，**不要因为「pilot 是入口」就写回去**。
@@ -19,3 +19,5 @@
 - [ ] FU-2 · B · src=2026-08-05 合并 #38/#39/#40/#41 后实测 · 2026-08-05 · safe-cleanup.sh 在 squash-merge 仓库里永远清不掉任何分支:本仓库 28 个本地分支,git branch --merged main 返回 0 个,因为 squash 后原 commit 不是 main 的祖先,而 safe-cleanup 只用 -d 永不 -D。这是继 #39(死代码)、#40(随机红灯)之后同一家族的第三个『守卫跑不起来』。正确改法:用 gh 核实『存在 headRefName==该分支且 state==MERGED 的 PR』作为已合并证据,再允许 -D;不能简单放开 -D
 - [ ] FU-3 · C · src=PR#42 review [Low] · 2026-08-05 · check-version-sync.sh 只比对 plugin.json 与 SKILL.md 两处。今天 README 没有硬编码版本号(核过),所以没问题;但哪天 README 加上版本,这条守卫不会知道。在脚本里写一句把范围钉住:『目前只有这两处声明版本』
 - [ ] FU-4 · B · src=PR#42 review [Low] + 2026-08-05 清理 28 个分支的实测 · 2026-08-05 · 补充 FU-2 的实现要点(今天手工做过一遍,算法已验证):① git branch --merged 和 git cherry 在 squash 仓库里【全部失效】—— cherry 对 12 个分支全报『未在 main』,因为 squash 重写补丁、patch-id 永不匹配;② 可用判据是『本地 tip == 或 是 任何一个已合并 PR 的 headRefOid 的祖先』,要先 git fetch origin pull/N/head 把 head 抓到本地;③ 【不能只按分支名匹配 PR】—— work-pr18 / fix-pr18-round2 / worktree-agent-* 这三个分支名从没当过 PR head,但 tip 就是 PR#18/#23 的已合并 head,按名字匹配会漏掉;④ 反向风险(评审提的):分支名可复用,同名分支删掉重开后内容不同,旧 MERGED PR 仍在 —— 祖先检查恰好挡住这种情况(重开的 tip 不会是旧 head 的祖先),但若改成只按名字匹配就会误删
+- [ ] FU-5 · B · src=2026-08-05 pilot 端到端测试(doctor+plan) · 2026-08-05 · pilot 的起跑门禁只认 docs_dir 下七个固定文件名,认不出等价(且更完整)的规划源。实测:Brood 的规划在 backlog/(4 个 milestone + 49 个带验收标准的 task + 2 个 ADR),check-docs.sh --strict 报 0/7、run 直接 fail-closed 拒跑;而 plan.md A.3 又明写『已有规划 → 不要重复造』—— 两条同时遵守不可能。本次用 docs/agent/ 做适配层(指向 backlog/ 的视图,不复制内容)绕过去了,但根治要给 check-docs.sh 加可配置规划源(如 .pilot.yml 声明 planning_source: backlog),否则每个用 backlog/issues/Jira 管规划的仓库都会被判未就绪
+- [ ] FU-6 · C · src=2026-08-05 pilot 端到端测试(doctor) · 2026-08-05 · doctor 第 4 步在单主干仓库里会误导:无 .pilot.yml 时默认 integration_branch=preview,doctor 发现它不存在就『提示先建』—— 但对单主干仓库正确答案是 integration_branch=main + 合并时用 --allow-trunk,不是去建一个 preview 分支。doctor 不知道这两件事是连着的。改法:检测到 preview 不存在但 default branch 存在时,提示单主干配置法并指向 --allow-trunk
@@ -0,0 +1,41 @@
+# Brood Progress — 实时状态
+
+> 「此刻在做什么」。规划见 [`roadmap.md`](roadmap.md)，任务台账见 [`tasks.md`](tasks.md)。
+> 本文件由 `pilot run` 持续更新。最后更新：2026-08-05
+
+## 当前分支与工作区
+
+- 集成分支：`main`（**单主干**，无 preview；见 `.pilot.yml` 的说明）
+- 本地分支：`main` + `cla-signatures`（CLA 签名存储，永久保留）+ `feat/pilot-auto-commit`（TASK-49 的原型，待做）
+- 工作区：干净
+
+## 在途 PR
+
+- **#45** `feat(pilot): FU-1/FU-2/FU-4 —— flag 改白名单 + safe-cleanup 支持 squash 仓库` — 等外部评审裁决
+
+## 2026-08-05 已交付
+
+八个 PR 合并：#36 → #40 → #39 → #38 → #41 → #42 → #43 → #44。
+
+主线是**把三个「跑不起来的守卫」修好**——三个都是本仓库自己写的，三个都是**用的时候**才现形，
+没有一个是审出来的：
+
+| PR | 病症 |
+|:---|:---|
+| #39 | `merge-pr` 因 `gh repo view --repo`（不存在的 flag）对任何仓库都必死 |
+| #40 | dist 可复现守卫被一个按墙钟算的字段带成随机红灯（15 分钟内就翻） |
+| #45（在途） | `safe-cleanup` 在 squash 仓库里永远清不掉分支（`git branch --merged` 恒返回 0） |
+
+其余：#38 定下「pilot 是唯一入口、配套能力按契约探测」；#41 输出 Cloudflare vs 官方定价选型分析；
+#42/#43/#44 逐条做掉评审的 Low 并把方法记进账本。
+
+同期：本地分支 28 → 3（每个删除都过机械核实）；必需检查 3 → 4 项（新增版本同步）。
+
+## 当前阻塞
+
+无硬阻塞。两个已知缺口记在 `followups.md`，都不阻塞主线。
+
+## 下一步
+
+1. 等 #45 裁决 → 合并 → `install.sh --copy` 发布到全局
+2. 走一轮完整 `pilot run` 交付一个真 task，验证「整机能跑」而不只是「配件好使」
@@ -0,0 +1,49 @@
+# Brood Research — 立项依据与已有调研
+
+> 完整调研文档在 `research/` 与 `backlog/docs/`。本文件只做索引 + 立项依据。
+
+## 为什么有 Brood
+
+Mycelium 生态横跨三个 org（AAStarCommunity / iDoris-ai / MushroomDAO）、几十个仓库。
+问题有两个，且性质不同：
+
+1. **对外**：没人（包括参与者自己）说得清「现在整体到哪一步了」。
+   → BroodBrain：把 `backlog/` 导出成只读静态站点，零后端、CDN 直发。
+2. **对内**：每个仓库的开发流程靠人记，危险动作（`git add -A`、直推主干、
+   没跑检查就开 PR）全靠自觉。
+   → pilot skill：把「有经验程序员的默认」固化成脚本层的确定性护栏。
+
+## 关键选型依据
+
+### 站点：为什么本地构建 + `dist/` 入库
+
+云端构建需要在 CI 里装 backlog.md CLI 并起服务，慢且脆；而站点更新频率低。
+代价是「改了内容忘记 build」——用 CI 守卫（`dist/ matches a fresh build`）补上。
+**这是一个已知取舍，不是疏忽。**
+
+### AI 模型与成本：见 `research/cloudflare-workers-ai/`
+
+两份文档：
+- `README.md` — Cloudflare Workers AI 能不能直接提供最新开源模型（结论：能，27 个 skill 可用）
+- `cost-analysis-api-vs-coding-plan.md` — **Cloudflare 照搬官方牌价，没有成本优势**；
+  结论是「日常开发买 coding plan、评审走官方 API」，并指出 Claude Code 的非交互用量
+  自 2026-06-15 起走独立额度——那可能才是 $200 不够用的真正原因
+
+### 评审：为什么解耦
+
+历史上 pilot 直接启动一个 PR-Daemon 进程。结果是 pilot 和那个 daemon 死锁在一起，
+装了 pilot 的机器都被迫带上一个可能坏掉的依赖。花 6 轮评审拆成纯接口契约
+（`reference/review-contract.md`）。**这是本仓库最贵的一条教训，写进了架构边界。**
+
+## License 边界
+
+Apache 2.0 + NOTICE + TRADEMARK 三件套，模板在 `protocol/license-templates/`，
+由 `/license-update` skill 批量同步到生态各 repo。
+
+## 待研究
+
+- **TASK-40 的 PreToolUse hook 怎么实现**——SKILL.md 称它是首要强制手段，
+  但没人验证过 Claude Code plugin hook 能否可靠拦下模型真正要跑的命令。
+  这是 pilot 从「劝告」变成「强制」的唯一路径，值得先做一个最小验证。
+- **pilot 门禁支持可配置的规划源**——本仓库的规划在 `backlog/`，
+  而门禁只认 `docs_dir` 下七个固定文件名，于是一个规划完备的仓库被判「未就绪」。
@@ -0,0 +1,47 @@
+# Brood Roadmap — Milestone → Feature
+
+> ⚠️ **本文件是视图，不是事实来源。** Brood 的规划事实来源是 `backlog/`（backlog.md CLI 管理），
+> 里程碑在 `backlog/milestones/`，任务在 `backlog/tasks/`。这里只做 pilot 需要的 M→F 摘要，
+> **不复制内容**——改规划请改 `backlog/`，不要改这里。
+>
+> 为什么需要这个文件：pilot 的起跑门禁 `check-docs.sh` 只认 `docs_dir` 下这七个文件名，
+> 认不出 `backlog/` 这种等价（且更完整）的规划。这是 pilot 的一个已知缺口，记在
+> `docs/agent/followups.md`。记录日期：2026-08-05
+
+## M1 — Phase 1: Genesis Launch
+
+目标：把生态的核心基础设施做出来，让「普通人无门槛用上 Web3」这条路第一次跑通。
+
+- **F1.1 Cos72 Chrome Extension** — 社区入口，Cards / Points / Perks 与核心模块（MyTask、MyShop、MyView）
+- **F1.2 AirAccount** — 隐形加密账户（抽象账户），用户不需要理解私钥
+- **F1.3 SuperPaymaster** — gas 代付，把「上链要先有币」这道门槛去掉
+- **F1.4 Sign90 / Comet ENS** — 签名基础版与 ENS 子域名服务
+
+## M2 — Phase 2: Community Expansion
+
+目标：从「能用」走到「社区能自己运转」。
+
+- **F2.1 KMS / TEE** — 可信执行环境，托管类能力的信任底座
+- **F2.2 Zu.Coffee** — 第一个真实商业 DApp，验证闭环
+- **F2.3 Bundler / OpenCrab** — 交易打包与面向个人的 agent
+
+## M3 — Phase 3: Ecosystem Maturity
+
+目标：从单点产品走到协议与网络效应。
+
+- **F3.1 Asset3** — 个人资产管理协议
+- **F3.2 Spores** — 病毒式传播 SDK
+- **F3.3 OpenNest / Park / TradeStar / CoinJar** — 扩容协议、可持续公共物品、交易训练、自托管存钱罐
+
+## M-R — Research（与 M1/M2/M3 并行，不排在它们之后）
+
+目标：论文与文章产出。研究任务可以横向关联到任意阶段的开发任务。
+
+- **FR.1 协议侧研究** — EOA Bridge、SuperPaymaster、CommunityFi
+- **FR.2 生态与教育** — iDoris.ai 课程、全球网络与 KMS 部署调研
+- **FR.3 成本与选型** — 见 `research/cloudflare-workers-ai/`
+
+## 当前重心
+
+M1 有 5 个 In Progress 任务，是主战场；M-R 有 5 个，属于并行产出。
+M2（2 个）、M3（3 个）已经起步但不是当前焦点。
@@ -0,0 +1,53 @@
+# Brood Spec — 数据模型 / 状态机 / 错误处理
+
+## 数据模型：任务文件
+
+`backlog/tasks/task-N - <标题>.md`，YAML frontmatter + markdown 正文。
+
+| 字段 | 说明 | 坑 |
+|:---|:---|:---|
+| `id` | `TASK-N` | |
+| `title` | 标题 | **含 `:` 必须加引号**——未加引号曾让解析器吐出空记录，10 个任务一次坏掉，且空记录仍带原始 markdown 进了公开搜索索引 |
+| `status` | `To Do` / `In Progress` / `Done` | 实测存在 `Done` 与 `"Done"` 两种写法并存，消费方要容忍 |
+| `milestone` | `m-1` / `m-2` / `m-3` / `m-r` | |
+| `dependencies` | 任务 id 列表 | 未 Done 的依赖会挡住挑选 |
+| `references` | 含 `github.com` URL 时 `sync-progress` 才能扫它 | |
+
+正文里 `<!-- SECTION:DESCRIPTION:BEGIN/END -->` 之间是 `sync-progress` 写进度的位置，
+`<!-- AC:BEGIN/END -->` 之间是验收标准。**改这些标记要同步改写入方**。
+
+## 导出契约（`/api/*.json`）
+
+- `tasks.json` 只含活动任务；`backlog/completed/` 由 `export-backlog.js` 单独合并进去，
+  合并前 `.sort()`（readdir 顺序依赖文件系统，不排序会让可复现守卫无理由报红）
+- `statistics.json` 的 `projectHealth.averageTaskAge` **按当前时间算**，
+  十几分钟就会跳一个数——比对前归一化，不删字段（SPA bundle 在读它）
+- 所有 payload 过 `sanitizeApiPayload()`：丢 `lastModified`，把
+  `filePath`/`projectPath`/`rootConfigPath` 转成仓库相对路径
+
+## 状态机：一个改动到 main 的路径
+
+```
+feature 分支
+  → git-guard.sh add <显式路径>        （拒 -A / 目录 / glob / pathspec magic）
+  → git commit
+  → git-guard.sh push origin <branch>  （拒推保护分支，解析所有 refspec 形态）
+  → preflight.sh run                   （跑 .pilot.yml preflight + scripts/ci/*.sh + build，
+                                         成功才写戳记，戳记绑定 HEAD sha）
+  → git-guard.sh pr-create             （无戳记 / 戳记属于别的 commit → 拒绝）
+  → 外部评审                            （契约：约 20 分钟出裁决）
+  → git-guard.sh merge-pr --allow-trunk （要求分支保护要求审批 + 该 PR 已 APPROVED）
+  → safe-cleanup.sh [--squash-merged]  （squash 仓库需要证据才 -D）
+```
+
+**每一步的失败都必须 fail-closed。** 判据：把该步依赖的外部条件拿掉（gh 卸载、
+token 无权限、分支无保护、戳记过期），它必须**拒绝并说明缺什么**，而不是放行、也不是
+沉默。「查不了」与「没有」在输出上必须能区分——这条踩过一次：子 shell 里设的状态
+返回后丢失，导致「无法核实」永远打印成「没有可清理的」。
+
+## 错误处理约定
+
+- 脚本用 `set -euo pipefail`；退出码 `2`=用法错、`3`=被护栏拒绝
+- 拒绝消息必须说**怎么修**，不能只说不行——只说「refused」的护栏会被绕过
+- 解析外部 JSON 时**只取 stdout**：把 stderr 折进来会让 shell hook 的诊断行污染 JSON，
+  于是每条分支都退化成「读不到」