From d6fdb2158cf4b6b35b4fbe7ffc6b6548ccea701c Mon Sep 17 00:00:00 2001 From: jhfnetboy Date: Wed, 5 Aug 2026 15:16:28 +0700 Subject: [PATCH] =?UTF-8?q?docs(pilot):=20=E8=A1=A5=20.pilot.yml=20+=20?= =?UTF-8?q?=E8=A7=84=E5=88=92=E5=B1=82=E4=B8=83=E4=BB=B6=E5=A5=97(?= =?UTF-8?q?=E9=80=82=E9=85=8D=E5=B1=82),=E9=97=A8=E7=A6=81=200/7=20?= =?UTF-8?q?=E2=86=92=207/7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 端到端测试 pilot 的产物。跑 `pilot doctor` 发现本地未就绪,`pilot plan` 补齐。 ## 为什么是「适配层」而不是规划本身 Brood 的规划事实来源是 `backlog/`:4 个 milestone、49 个带验收标准的 task、2 个 ADR —— 比多数仓库完整。但 `check-docs.sh --strict` 报 **0/7**,`run` 直接 fail-closed 拒跑, 因为它只认 `docs_dir` 下那七个固定文件名。 而 `plan.md` A.3 明写「已有规划 → 不要重复造」。**两条同时遵守是不可能的。** 所以七件套写成**指向 backlog/ 的视图**:每份开头声明「本文件是视图,不是事实来源, 改规划请改 backlog/」,内容是摘要 + 怎么读 + 怎么挑下一个,不复制任务条目。 ## 内容不是模板填空 七份都写了本仓库的真实约束,其中几条是今天用出来的教训: - `architecture.md`:分层强制 ①GitHub 分支保护 ②hook(未建) ③git-guard ④散文, 「越往下越不可信」;任何『这条护栏保证了 X』必须能指到 ① 或 ③ 的具体行 - `architecture.md`:**放权必须先建立证据** —— `--allow-trunk` / `--squash-merged` 都是先要服务端证明,不是「为了让守卫能跑就削弱它」 - `spec.md`:每步失败必须 fail-closed,且「查不了」与「没有」在输出上**必须可区分** (这条踩过:子 shell 里设的状态返回后丢失,「无法核实」永远打印成「没有可清理的」) - `spec.md`:解析外部 JSON **只取 stdout** —— 折进 stderr 会让 shell hook 的诊断行污染 JSON - `acceptance.md`:单列「已知未达标项」,包括三阶段主流程从未端到端跑过、 以及 SKILL.md 自称的首要强制手段(PreToolUse hook)实现为空 ## .pilot.yml `integration_branch: main` —— Brood 是单主干,pilot 默认的 `preview` 对本仓库是错的。 不设 `preflight:`,因为 preflight.sh 已自动发现 `scripts/ci/*.{sh,py}` 与 build, 显式再写一条只会让同一个检查跑两遍。 ## 账本新增两条(测试挖出来的 pilot 缺陷) - FU-5(B):门禁应支持可配置规划源,否则每个用 backlog/issues/Jira 管规划的仓库 都会被判「未就绪」 - FU-6(C):doctor 在单主干仓库会把人往「去建 preview」引,而正确答案是 `integration_branch: main` + `--allow-trunk`;doctor 不知道这两件事是连着的 验证:`check-docs.sh --docs-dir docs/agent --strict` → `ok=7/7`、 `PILOT_DOCS: ready — planning layer complete, safe to run unattended.`、rc=0 Claude-Session: https://claude.ai/code/session_01CmAW1q62bBtjT99inZeyLk --- .pilot.yml | 15 +++++++++++ docs/agent/acceptance.md | 37 ++++++++++++++++++++++++++ docs/agent/architecture.md | 48 ++++++++++++++++++++++++++++++++++ docs/agent/followups.md | 2 ++ docs/agent/progress.md | 41 +++++++++++++++++++++++++++++ docs/agent/research.md | 49 +++++++++++++++++++++++++++++++++++ docs/agent/roadmap.md | 47 +++++++++++++++++++++++++++++++++ docs/agent/spec.md | 53 ++++++++++++++++++++++++++++++++++++++ docs/agent/tasks.md | 52 +++++++++++++++++++++++++++++++++++++ 9 files changed, 344 insertions(+) create mode 100644 .pilot.yml create mode 100644 docs/agent/acceptance.md create mode 100644 docs/agent/architecture.md create mode 100644 docs/agent/progress.md create mode 100644 docs/agent/research.md create mode 100644 docs/agent/roadmap.md create mode 100644 docs/agent/spec.md create mode 100644 docs/agent/tasks.md diff --git a/.pilot.yml b/.pilot.yml new file mode 100644 index 0000000..ec98cc2 --- /dev/null +++ b/.pilot.yml @@ -0,0 +1,15 @@ +# pilot 配置 — Brood +# +# 注意 integration_branch = main：Brood 是单主干仓库，没有 preview 集成分支。 +# pilot 的默认值是 preview，那对本仓库是错的。合并走 +# `git-guard.sh merge-pr --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， +# 那已经覆盖本仓库全部检查。显式写一条只会让同一个检查跑两遍。 diff --git a/docs/agent/acceptance.md b/docs/agent/acceptance.md new file mode 100644 index 0000000..a7a5cfc --- /dev/null +++ b/docs/agent/acceptance.md @@ -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` 和直推**。 diff --git a/docs/agent/architecture.md b/docs/agent/architecture.md new file mode 100644 index 0000000..e504b07 --- /dev/null +++ b/docs/agent/architecture.md @@ -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 是入口」就写回去**。 diff --git a/docs/agent/followups.md b/docs/agent/followups.md index 4ee077e..d372925 100644 --- a/docs/agent/followups.md +++ b/docs/agent/followups.md @@ -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 diff --git a/docs/agent/progress.md b/docs/agent/progress.md new file mode 100644 index 0000000..194cf66 --- /dev/null +++ b/docs/agent/progress.md @@ -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，验证「整机能跑」而不只是「配件好使」 diff --git a/docs/agent/research.md b/docs/agent/research.md new file mode 100644 index 0000000..3a904f9 --- /dev/null +++ b/docs/agent/research.md @@ -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` 下七个固定文件名，于是一个规划完备的仓库被判「未就绪」。 diff --git a/docs/agent/roadmap.md b/docs/agent/roadmap.md new file mode 100644 index 0000000..ac33296 --- /dev/null +++ b/docs/agent/roadmap.md @@ -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 个）已经起步但不是当前焦点。 diff --git a/docs/agent/spec.md b/docs/agent/spec.md new file mode 100644 index 0000000..1b5a49f --- /dev/null +++ b/docs/agent/spec.md @@ -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` 才能扫它 | | + +正文里 `` 之间是 `sync-progress` 写进度的位置， +`` 之间是验收标准。**改这些标记要同步改写入方**。 + +## 导出契约（`/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 （拒推保护分支，解析所有 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， + 于是每条分支都退化成「读不到」 diff --git a/docs/agent/tasks.md b/docs/agent/tasks.md new file mode 100644 index 0000000..1a40206 --- /dev/null +++ b/docs/agent/tasks.md @@ -0,0 +1,52 @@ +# Brood Tasks — 执行台账 + +> ⚠️ **本文件是视图，不是事实来源。** 任务的事实来源是 `backlog/tasks/*.md`（backlog.md CLI）， +> 每个任务自带 `status` / `milestone` / `dependencies` / `references` / Acceptance Criteria。 +> **改任务请改 `backlog/`，不要改这里。** 本文件只说明「怎么读它、怎么挑下一个」。 + +## 怎么看任务 + +```bash +ls backlog/tasks/ # 全部任务文件 +npx backlog task list # CLI 视图 +grep -l "^status: In Progress" backlog/tasks/*.md # 在做的 +``` + +站点视图：`pnpm run build` 后 `dist/`，或已部署的 BroodBrain 页面。 + +## 状态机 + +`To Do` → `In Progress` → `Done`。这是 backlog.md CLI 的三态，**不是** pilot +`reference/task-schema.md` 里的 READY/PR_OPEN/BLOCKED 五态。两套状态并存是事实， +pilot 侧把 `To Do` 当 READY 读、`In Progress` 当在途读即可，不要试图在 backlog 里造新状态。 + +## 当前分布（2026-08-05 实测） + +| 状态 | 数量 | +|:---|---:| +| To Do | 27 | +| In Progress | 15 | +| Done | 7 | +| **合计** | **49** | + +按里程碑看 In Progress：M1 五个（主战场）、M-R 五个、M3 三个、M2 两个。 + +## 怎么挑下一个 + +1. 优先 **M1** 的 `To Do`——它是当前重心（见 `roadmap.md`）。 +2. 该任务必须能写出**机器可验证的验收命令**；写不出说明还太大，先拆。 +3. 有 `dependencies:` 且依赖未 Done 的，跳过。 +4. 涉及产品方向 / 验收标准 / 架构的未知 → 标 BLOCKED 记下问题，**不猜**（SKILL.md 硬约束 7）。 + +## 本仓库自己的任务（pilot / CI 方向） + +这些是 Brood 作为「工具仓库」自己的活，和生态业务任务并列在 `backlog/` 里： + +- **TASK-40** — pilot PreToolUse hook 机械拦截 `git add -A` / 推主干。**SKILL.md 自称这是首要强制手段，但状态仍是 To Do**，也就是最强的那句承诺目前实现为空。 +- **TASK-39** — sync-progress 的 gh api 校验，防伪造进度 +- **TASK-47** — 文档类 PR 对照真实代码 + JSON lint +- **TASK-43** — 涉钱/gas 任务的机器可验证验收 + +## 不阻塞的跟进项 + +见 `followups.md`（append-only 账本，`scripts/followups.sh` 维护）。