@haiyangbg/buildbeat 0.0.0 → 1.20.0

package/templates/ARCHITECTURE.md

@@ -0,0 +1,50 @@
+# ARCHITECTURE.md — <项目名> 全栈总图(AI 会话接手按需读这份)
+
+> 一句话:<项目是什么、给谁用、核心取舍>。
+> 本文是**顶层总图**:架构链路 + 文件夹 + 基础设施标识。**按需读,不自动装载**(自动装载的是根 `AGENTS.md`)。各子系统细节在各代码子仓自己的 `AGENTS.md`/`README.md`,文末有索引。
+> 🔴 凭据(key / DB 密码 / token)一律**只标位置、不写值**。任何会话不得把凭据写进任何文档或代码。
+
+## 0. 架构链路
+
+```
+<用户入口>
+  ▼
+<前端/客户端>(<仓名>,<部署单元>)
+  ▼
+<网关/服务A>  ──▶ <审计/可观测>
+  ├──▶ <服务B>
+  └──▶ <服务C>
+```
+
+## 1. 文件夹
+
+```
+<项目根>/
+├── AGENTS.md / ARCHITECTURE.md / 指挥台.md / contracts/ / design/ / pm/ / scripts/
+├── <代码仓1>/        # ★ <说明>;详见其 AGENTS.md
+└── <代码仓2>/        # ★ <说明>
+```
+
+## 2. 基础设施标识(资源变动时更新本节;细节别往这塞)
+
+| 项 | 值 | 说明 |
+|---|---|---|
+| <部署平台/区域> | | |
+| <应用/服务清单:名称+ID+实例> | | |
+| <入口/域名/LB> | | |
+| <数据库/缓存> | | |
+
+### 凭据位置(🔴 只读取,不外泄、不写值)
+- <服务A 凭据> → `<路径/获取命令>`
+- <运行时 env 实查> → `<平台 CLI 命令>`
+
+## 3. 红线
+见根 `AGENTS.md §3`(凭据/不 add -A/不未授权部署/CHANGELOG/写者≠审者)。
+
+## 4. 子项目文档索引(改哪块先读哪份)
+
+| 改动范围 | 先读 |
+|---|---|
+| <代码仓1> | `<代码仓1>/AGENTS.md` + `CHANGELOG.md` |
+| <代码仓2> | `<代码仓2>/README.md` |
+| 跨边界契约 | `contracts/PROTOCOL.md` |

package/templates/BUILDBEAT.md

@@ -0,0 +1,13 @@
+# BUILDBEAT.md — 本项目的协作骨架版本标记
+
+**本项目使用 BuildBeat `v<X.Y>`**(<yyyy-mm-dd> 拷入)
+**协调层布局:`<默认|紧凑>`**(默认 = 脚本在 `scripts/`;紧凑 = 在 `pm/scripts/`,见上游 SKILL §3)
+来源:<https://github.com/HaiYangBG1/BuildBeat>
+
+## 升级
+
+对照上游 [CHANGELOG.md](https://github.com/HaiYangBG1/BuildBeat/blob/main/CHANGELOG.md),从本文件记录的版本**往后**逐版看「拷出项目升级」标注的文件,同步后更新上面的版本行。拿不准就让 AI 会话对比上游 `templates/` 与本项目对应文件的差异。
+
+## 回灌(比升级更重要)
+
+本项目踩到 BuildBeat **没覆盖的新坑**(新反模式/机制漏洞)→ 回上游 `lessons.md` 登记一条(症状→根因→解药),提 issue/PR 或直接改上游仓。换期压缩仪式的 checklist 里有"回灌一问",别跳过——没有回灌,N 个项目的坑不会变成组织资产,只会各踩各的。

package/templates/CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md — 指针(🔴 勿在此处写内容)
+
+本工作区的会话路由、协作总线十条规则、红线,**单点在同目录的 [`AGENTS.md`](AGENTS.md)** —— 请立即读取那份。
+
+> 本文件只为兼容「只认 `CLAUDE.md` 这个文件名的工具」而存在,**永远保持这几行**。
+> 往这里复制任何规则 = 两份文档必然漂移(上游 `lessons.md` 第 1 条:SSOT 腐烂)。
+> 也不要改成符号链接:Windows 上 git 默认 `core.symlinks=false`,clone 出来会静默退化成一个内容是路径字符串的普通文件,装载即失效。

package/templates/contracts/PROTOCOL.md

@@ -0,0 +1,32 @@
+# <项目名> 跨边界契约 · PROTOCOL(SSOT)
+
+> **这是跨仓/跨服务边界唯一的契约入口。** 谁改接口行为,先改这里;谁要接接口,先读这里。
+> 🔴 规则:**协议变更不照单全收** —— 用 实测 / 读对端代码 / 查部署配置 独立核查后再信,并在 §3 登记一行。
+> 🔴 本文件**不含任何 key / 凭据明文**。
+> 同仓内部的"前后端"接口优先用**共享类型/schema 由编译器强制**,不进本文件;本文件只管跨服务、跨语言、跨部署单元的边界。
+
+**契约快照对应版本:`<vX.Y.Z>`**(<上线日期>)。
+> 🔴 **线上实况唯一查询口 = `bash scripts/bus-check.sh`**;本行只标「本快照写就时对应的版本」,其它文档一律不写「当前线上 vX」(规则⑨)。
+
+> 多仓项目逐仓填写下面的显式来源 map；单仓项目删除整个 block。`contract` 指向含唯一「契约快照对应版本」行的仓库相对 Markdown，`deployment` 填 `scripts/bus-baseline.json` 的 app key；确认无部署填 `n/a`。不要靠目录名或自然语言猜版本关系。
+
+<!-- buildbeat-multirepo-map:v1
+repo=<代码子仓1>|contract=contracts/PROTOCOL.md|deployment=<bus-baseline.json app 名或 n/a>
+-->
+
+---
+
+## 1. 当前契约快照
+
+### <边界A:服务X ↔ 服务Y>
+| 端点/字段 | 行为 | 备注 |
+|---|---|---|
+| | | |
+
+## 2. 🔴 当前关键对齐点(开工前各域必须一致)
+1. <对齐点>
+
+## 3. 契约变更记录(changelog · 倒序)
+| 版本 | 日期 | 变更 | 独立核查 |
+|---|---|---|---|
+| | | | <怎么核的:实测命令/代码行/配置查询> |

package/templates/gitignore.template

@@ -0,0 +1,19 @@
+# 拷入新项目根后改名为 .gitignore(模板文件名不带点,避开 cp 通配符丢点文件的坑)
+
+# macOS
+.DS_Store
+
+# 凭据 / 本地环境(红线①:凭据不入 git)
+*.env
+.env
+.env.*
+*.local
+*.key
+*.pem
+
+# verify-status 的「上次全绿」标记(本地实查产物,不入 git)
+.last-green-*
+
+# 代码子仓(各自独立 git,meta 仓不跟踪;按实际仓名替换)
+/<代码仓1>/
+/<代码仓2>/

package/templates/pm/NOW.md

@@ -0,0 +1,26 @@
+# NOW — 当前冲刺指针(各工作包/AI 视角会话开工先读这里)
+
+> 本文件**永远只是薄指针**:当前期是什么 + 看哪些文件。🔴 **禁止在这里堆流水日志**(那是 `status/<域>.md` 的事;NOW 长肥 = SSOT 腐烂的开端)。
+> 🔴 **线上版本不写在任何文档里**(规则⑨):查 `bash scripts/bus-check.sh`;契约快照对应版本只看 `contracts/PROTOCOL.md` 头部。
+
+**当前期:<期名>**(<一句话状态>)
+**本期轨道:<快轨|标准轨|重轨>**
+
+| 看哪 | 文件 |
+|---|---|
+| 🧭 当期看板 | `<期>-看板.md` |
+| 🗳 拍板台账(决策单点) | `decisions.md` |
+| 🔌 契约 | `contracts/PROTOCOL.md` |
+| 📊 各 AI 视角状态(各写各的) | `status/产品.md` · `status/全栈.md` · `status/测试.md` |
+| 🔁 在途变更提案 | `changes/`(在途几个跑 bus-check 看,别在这里记) |
+| 📦 历史期归档 | `archive/` |
+
+---
+
+### 换期 checklist(当前工作包 Builder / 产品视角)—— 含压缩仪式
+1. **压缩仪式**:① 当期 看板/需求/todo/验收清单 `git mv` 进 `archive/<期>/`(归档文件超 40 个会触发 pre-commit 闸④,这一单用 `BUS_ALLOW_BULK=1 git commit` 提交);② `status/*.md` 全文 `cp` 进 `archive/<期>/status-<域>-<期>全程.md`,live 文件截断只留「当前基线 + 最近 1 条 + 归档指针」;③ NOW 流水清零(只留指针区);④ 核对本期证据产物已在 `archive/<期>/evidence/`(走查图/E2E 报告生成时就该写进去,换期零搬运),工作区根与 pm/ 无散落临时文件。
+2. 新建下一期 `<期>-看板.md`(+需求/todo),回来把上表指针换掉、更新「当前期」「本期轨道」两行。
+3. `decisions.md` 追加一行「换期」;新看板开第一个阶段门。
+4. **回灌一问**:本期踩到 BuildBeat 没覆盖的新坑了吗?有 → 回上游 lessons.md 登记(见根 `BUILDBEAT.md`)。
+
+> 全工作区换期 = 只动本文件的指针区。看板文件名**不得**写死进 `AGENTS.md` 等别处。

package/templates/pm/adr/ADR-0000-template.md

@@ -0,0 +1,25 @@
+# ADR-0000: <标题>
+
+- Status: Proposed
+- Date: <yyyy-mm-dd>
+- Superseded by: n/a
+
+## Context
+
+<为什么现在必须做这个长期技术决定>
+
+## Decision
+
+<最终选择及其边界>
+
+## Consequences
+
+<正向、负向与回滚影响>
+
+## Alternatives considered
+
+<方案 A / B / C 及未选原因>
+
+## Related contracts / work packages / evidence
+
+<工作包 / 契约 / evidence 路径或 n/a>

package/templates/pm/adr/README.md

@@ -0,0 +1,15 @@
+# ADR 使用约定
+
+ADR 只承载长期、难回退的技术决定；普通产品拍板、Gate 确认、短期可逆选择继续写在 `pm/decisions.md`。
+
+满足任一条件时建议从 `ADR-0000-template.md` 复制一份新文件：
+
+1. 改变核心运行时、框架、数据库或部署方式；
+2. 改变跨服务或跨仓架构；
+3. 改变关键数据模型或公共接口策略；
+4. 形成长期、难以回退的技术约束；
+5. 推翻或替代此前 ADR。
+
+命名使用 `ADR-NNNN-kebab-case.md`，编号单调递增。Status 只允许 `Proposed / Accepted / Rejected / Superseded`。若为 Superseded，必须填写一个存在的仓库根相对路径，例如 `pm/adr/ADR-0002-new-choice.md`；新 ADR 解释替代原因，旧 ADR 保留不删除。
+
+ADR 收敛后仍在 `pm/decisions.md` 追加一行索引，指向 ADR 和实际回写落点；ADR 不管理团队成员、审批人或组织权限。

package/templates/pm/changes/README.md

@@ -0,0 +1,44 @@
+# pm/changes/ —— 变更提案(治跨域 race + drift)
+
+> 跨域变更(尤其动**契约/需求/多域**的)**不要直接抢改看板/契约文件** —— 先在这写一个独立 change。冻结前允许在已批准目标内持续收敛草案和补证;一次冻结决策后先把批准的 delta 合并进 canonical,再让新语义进入共享实现。
+
+## 何时用
+- **重轨**改动:跨期 / 契约变更 / 多域大改。小改快轨、单需求标准轨,都不用建 change。
+
+## 流程
+1. **开草案** → 新建 `pm/changes/<yyyymmdd>-<短名>.md`(用下方模板),标 `草案收敛`。建草案本身不等于申请人批。
+2. **收敛** → 在已批准 objective/in_scope 内自查、补证、做可抛弃原型;把需要人取舍的独立决策变量汇入当期看板「决策收件箱」(默认 2–5 个一包,确实只有 1 个就单项)。验收条目和推导约束不逐项问。
+3. **冻结** → 到 Gate 或关键路径确实被阻塞时,一次提交决策包:批 / 改 / 否。收敛后在 `../decisions.md` 记一行,先把批准的 Delta 合并进 canonical(`contracts/PROTOCOL.md` / 需求文档),再把 change 标 `已冻结`。冻结前草案不得被冒充 canonical,也不得让未批语义进入共享实现。
+4. **实现** → 各域按已冻结 change 的"分工"动手,轻量机器闸每次提交、受影响测试按变更批次;只把实现期新增的失败态、不可达状态、默认值/阈值、fail-closed 方向记进同一份「实现语义清单」,不为每个小任务新建完整审查报告。
+5. **候选** → 先完成实现/写者自查,把自行发现的鉴权/租户/Secret/fail-closed/持久化问题合并收敛进同一候选。只有要修改**已冻结对外契约**或产生不可逆副作用才 STOP_NOW,获批后按一个风险批次做 `risk-delta`;不得边改 candidate 边开 reviewer。
+6. **review-ready + 核查 + 归档** → 所有候选仓 `HEAD=candidate` 且干净、受影响/全量 L3 与真渲染证据绿、无已知待修后,对里程碑候选做一次完整核查;P0/P1 合并修完后做一次 closure。产品域确认 canonical 与已冻结、已实现语义一致后归档。reviewer 返回前 hash 变化则旧审查 `SUPERSEDED`,重新收敛后再核;同一 candidate 合并前复用结论。
+
+## 模板(复制改)
+```md
+# CHANGE: <短名>
+- 状态:草案收敛 / 待冻结 / 已冻结 / 实现中 / 已归档
+- 发起:<域> ｜ 日期:<yyyy-mm-dd> ｜ 轨道:重 / 标准
+- 工作包:<当期看板 objective 或锚点>
+- 冻结基线:<未冻结 / decisions.md 日期+决策包>
+## 动机(为什么)
+## Delta(改什么 —— 逐条标 ADDED / MODIFIED / REMOVED)
+- [MODIFIED] PROTOCOL.md §X:<旧 → 新>
+## 决策变量(只列人必须取舍的变量;推导约束不列)
+| ID | 取舍 | 推荐值 + 理由 | 另一选择的后果 | 状态 |
+|---|---|---|---|---|
+| D1 | | | | 待收件箱 / 已收敛 |
+## 保护项(这次改动不许伤到的既有能力,逐条列)
+## 分工(谁做)
+| 域 | 做什么 | commit |
+|---|---|---|
+## 实现语义清单(只记实现期新产生的自由度;没有就写「无」)
+| 类别 | 决定/发现 | 契约覆盖 | 处置 |
+|---|---|---|---|
+| 新失败态 / 不可达状态 / 默认值或阈值 / fail-closed 方向 | | 已覆盖 / 需回流 / 改实现 | |
+## 里程碑候选
+- base:<hash 或多仓 hash 集>
+- candidate:<hash 或多仓 hash 集>
+- 机器证据:<测试 / gitleaks / bus-check / L3-L4 指针>
+## 验收点(怎么验 —— 核查门逐条核,必带可核验证据)
+- [ ] <证据:测试命令 / 文件:行 / 线上实测 / 截图>
+```

package/templates/pm/decisions.md

@@ -0,0 +1,12 @@
+# decisions — 拍板台账(全工作区唯一决策单点)
+
+> **规则(总线⑨)**:一个真实决策包收敛后,**第一动作 = 在此追加一行**(倒序),然后才去回写受影响的 SSOT(契约/设计稿/看板/todo);「回写」列登记落点,没回写完 = 欠账可见。单个独立决定也可以是一项决策包。
+> 验收项先分成「人必须取舍的独立变量」与「由已选变量/现有契约推导的约束」:只记录前者;后者直接回写并随候选验收。`3/14 → 11/14 → 14/14` 之类部分进度只留在当期看板「决策收件箱」,不得制造三条永久拍板。
+> 决策单元沿用看板收件箱的包ID;用户分轮回答或要求解释时不换号,直到整包收敛后在本表出现一次。
+> 重轨变更照走 `changes/` delta 提案,此处一行指向提案,不重复正文。
+> 改变核心技术栈、跨仓架构、关键数据模型或长期难回退约束时，按 pm/adr/README.md 建独立 ADR；本表仍追加一行 ADR 索引与实际回写落点。未启用 ADR 目录时不因此报错。
+> 「拍板人」单人项目就固定写你的名/代号;多人或要审计时(Gate3 合并与 Gate4 上线未必同一人批),谁批的由此可查。
+
+| 日期 | 拍板人 | 决策包 | 回写(落点 → 状态) |
+|---|---|---|---|
+| <yyyy-mm-dd> | <谁> | 【<包ID>】<默认 2–5 个真实取舍的收敛结论;单项决定直接写一句> | <文件/落点> → ✅/⏳ |

package/templates/pm/status/README.md

@@ -0,0 +1,32 @@
+# pm/status/ —— 各 AI 视角状态文件(治看板 race)
+
+> 一个 Builder 端到端拥有当前工作包;产品/全栈/测试只是可选 AI 视角。**每个视角只写自己的 `pm/status/{视角}.md`**(带 commit hash),别人只读 —— 物理上消除"同文件互踩"。NOW/看板做聚合视图,这里不记录成员或岗位。
+
+## 约定
+- 写法:**倒序**,每条带 commit hash / 版本 / 状态(✅完成 / 🔄进行 / ⏸阻塞)。
+- 🔒 **hash 必须写在反引号里**(`` `hash` `` 或 `` `仓名 hash` ``):bus-check 的幽灵 hash 核验**只认反引号内的 token**——约定即解析规则,裸写的 hash 不被核验。
+- hash 指向**工作包交付候选/测试或评审报告**的 commit,不是 status 行自身 commit(那会形成不可能的自引用并诱发无穷 status 提交)。同仓交付先提交候选,再集中写一次 status;阻塞且无新候选时写已核基线 hash +「无新候选」,不得臆造。
+- **条目克制**:下游只需要「做了什么 + hash + 证据指针」,长篇分析放报告文件、此处放链接。
+- **按工作包更新**:原子 commit 可保持细粒度,但 status 只在工作包完成、里程碑候选形成或真实阻塞时更新一次;不得为每个子任务/文档/commit 追加一条并把它当成向用户交接。
+- reviewer 结论只写 `mode + candidate hash 集 + P0/P1 是否清零 + 报告/closure 表指针`;不得把问题原文和逐轮整改全文复制进 status。
+- 跨域要对齐的(契约/依赖)→ 走 `../changes/` 变更提案;决策包收敛 → 先落 `../decisions.md`(规则⑨)。
+- 🗜 **压缩仪式(换期时当前工作包 Builder / 产品视角执行)**:当期条目全文 `cp` 进 `../archive/<期>/status-{视角}-<期>全程.md`,live 文件截断只留「当前基线 + 最近 1 条 + 归档指针」。
+
+## 收工核对
+
+1. 工作包真正到达 terminal condition,受影响测试/必要的 L3、L4 证据已落盘。
+2. candidate/report hash 已回读可解析;完成工作包的看板块含唯一 `**证据**:` 行。
+3. contracts / decisions / 当期看板 / 本视角 status 与候选一致,无流水式重复记录。
+4. 跑 `bash scripts/bus-check.sh --strict`;非阻断 warning/unverified 也写入收尾边界,不外推为全局已验证。
+
+## 模板(每个域文件)
+```md
+# 状态 · <域>
+> 只此域写,别人只读。倒序。
+
+## 当前基线
+- <长期成立的事实;会腐的事实(版本等)放"怎么查"的指针>
+
+## 倒序日志
+- **<yyyy-mm-dd>** 工作包:<objective 的结果> · candidate/report `<hash 或 hash 集>`(无新候选则写 base `<hash>`) · 证据:<命令/文件:行/截图路径> · ✅/🔄/⏸
+```

package/templates/pm//345/275/223/346/234/237/347/234/213/346/235/277.md

@@ -0,0 +1,62 @@
+# <期名> · 协调看板
+
+> 谁做什么、什么顺序、卡点在哪。工作包完成口径 = **用户级结果 + commit hash + 可核验证据**(核查门);子任务完成不等于会话结束。
+> 线上实况:`bash scripts/bus-check.sh`。拍板记 `decisions.md`。
+
+## 当前工作包(每个会话同时只认领一个;不同目标可有少量并行包)
+
+> 每个需求/功能工作包由一个 Builder 端到端负责;下方产品/全栈/测试只表示该工作包调用的 AI 专业视角,不是人类岗位交接或人员分配。
+
+### WP-1 · <工作包名>
+
+- **objective**:<这轮最终要交付什么结果,不用文件名代替>
+- **AI视角**:<产品 / 全栈 / 测试;按需调用,各自仍只写自己的边界>
+- **in_scope**:<为达成结果可自动继续的关联任务/AI视角/文件边界>
+- **terminal_condition**:<带证据完成 / 必须由人处理的真实阻塞 / 用户明确的检查点>
+- **状态**:🔄进行 / ⏸阻塞 / ✅完成
+- **证据**:<完成时填一条可核验的仓库相对路径 / candidate hash;未完成留空>
+
+> 同一工作包可由多个域接力;复制本小节即可增加并行包,但不要按文件造包。原子 commit 可以细;单个文档提交、reviewer 返回、status 回写、普通 P2 只是包内事件。只要还有安全、可逆、在 `in_scope` 内的工作,会话继续推进,不结束等用户说“继续”。
+
+## 决策收件箱(只收 BATCH_AT_GATE;默认一次提交 2–5 个真实取舍,确实只有 1 个就单项)
+
+| 包ID | 变量ID | 真实取舍 | 推荐值 + 理由 | 另一选择的后果 | 截止 Gate | 状态 |
+|---|---|---|---|---|---|---|
+| DP-<Gate>-01 | D1 | | | | Gate1 / Gate2 / Gate3 | 待批 / 已收敛 |
+
+> 能实查的事实、已批准范围内的推导结论和普通实现细节不进收件箱;STOP_NOW 事项立即停在动作前问,不可混在批量队列里。用户分轮回答/要求解释时沿用同一包ID、只更新本表;整个决策包收敛后再在 `decisions.md` 记一行。
+
+## 阶段门
+
+- Gate1: pending
+- Gate2: pending
+- Gate3: pending
+- Gate4: pending
+
+> 上述四行是机器权威令牌:`n/a` 必须同行带 `理由:`;`passed` 应同行带 `决策: pm/decisions.md:<行号>` 或 `证据:` 可追溯引用。决策须精确到已存在的日期表格行，本地证据统一归档到 `pm/archive/<期>/evidence/`。下表仅作给人的展示与进度摘要。
+
+| 阶段 | 产出 | 负责 | 状态 |
+|---|---|---|---|
+| ① 需求(⛔Gate1 人批) | 需求与决策 | 产品 | ☐ |
+| ② 设计(⛔Gate2 人对**真渲染原型**批,规则⑩) | `design/design_<N>期/`(含可渲染 HTML) | 外部设计工具 | ☐ |
+| ③ 实现 | 代码 + 契约 + 实现语义清单;机器闸每提交 | 全栈 | ☐ |
+| ④ 验证 + 核查门 | review-ready(`HEAD=candidate` + 干净 + L3/渲染绿 + 无待修) + milestone **一次** + P0/P1 合并 closure | 测试 + 产品 | ☐ |
+| ⑤ 上线(⛔Gate3 合并 / ⛔Gate4 上线,人批) | 部署 + CHANGELOG | 全栈 | ☐ |
+
+## 能力视角表(需求 → 调用哪些 AI 视角)
+| 需求 | 全栈 | 测试 | 备注 |
+|---|---|---|---|
+| <需求1> | ★ | E2E+走查 | |
+
+## 🔴 关键对齐点(开工先定,别各做各的)
+1. <跨边界接口/字段/机制 约定;契约口径落 `contracts/PROTOCOL.md`>
+
+## 挂账(实时;工作包认领后各 AI 视角写回自己的 status,此处只改 ☐/✅)
+| # | 项 | 域 | 状态 | 依据/出处 |
+|---|---|---|---|---|
+| 1 | | | ☐ | |
+
+## 验收口径
+<对照需求清单 + 设计稿逐屏;上线前必过的清单>
+
+> 核查节奏:首次 milestone 前写者先收敛,文件数/草稿/归档/status/P2 不触发 reviewer;每工作包每 Gate 默认一次 milestone,P0/P1 合并修完后一次 closure。同一 candidate 合并前复用结论;reviewer 返回前 hash 变化则旧审查 `SUPERSEDED`,不得边改边 delta。