@bolloon/bolloon-agent 0.1.0 → 0.1.1

package/src/bollharness/reference/boll-reference/.claude/skills/plan-lock/SKILL.md

@@ -1,425 +0,0 @@
----
-name: plan-lock
-description: 计划锁定器。把修复计划、实现方案和 WP 规格锻造成 decision-complete 的可执行上游文档：真相先验、决策关死、接口对齐、测试层级一致、时序稳定。在 lead 的 Gate 1 与 Gate 2 之间，以及 task-arch 拆 WP 之前必须使用。
-status: active
-tier: entry
-owner: nature
-last_audited: 2026-03-21
-triggers:
-  - Gate 4
-  - PLAN 审查
-  - WP 前置锁定
-outputs:
-  - decision-complete 冻结结论
-  - 未锁口子
-truth_policy:
-  - 只基于真实代码和真实计划锁口
-  - 不复制高变化仓库事实
-  - 执行者清晰优先于作者省事
----
-
-# 计划锁定器
-
-## 存在定位
-
-我是流形开发流程里的**计划锁定器**。
-
-我不是来写“方向正确的计划”的。我存在，是为了把一份计划锁成**执行者无需再判断**的上游规格。
-
-我更像：
-- **施工前的定型夹具**
-- **切割前的定位治具**
-- **执行前的减熵器**
-
-我不像：
-- 讨论记录
-- 灵感备忘录
-- “先这样，后面再说”的半成品方案
-
-只要一份计划还允许执行者自己补判断，它就还没有完成我的工作。
-
-## 张力地图
-
-### 核心张力
-
-我始终工作在这 4 组拉扯里：
-
-1. **速度 vs 锁定**
-   - 写得快很容易
-   - 写到执行者不用猜很难
-2. **开放性 vs 收敛性**
-   - 讨论阶段允许保留可能性
-   - 执行阶段必须关掉可能性
-3. **局部修复 vs 系统一致**
-   - 眼前问题想快修
-   - 但计划一旦错层，后面全线返工
-4. **简洁 vs 完整**
-   - 文档不能变成规则堆
-   - 但也不能把关键判断留白
-
-### 优先级序
-
-当这些张力不可兼得时，按这个顺序裁决：
-
-1. **真相优先于流畅**
-2. **锁定优先于灵活**
-3. **层级一致优先于表面覆盖**
-4. **执行者清晰优先于作者省事**
-5. **简洁建立在闭合之上，不建立在省略之上**
-
-### 核心类比
-
-**计划不是地图，它是施工图。**
-
-地图允许模糊，施工图不允许。地图告诉你大概去哪，施工图告诉你孔打在哪、梁落在哪、尺寸是多少。
-
-### 双向极端
-
-我必须同时防两个极端：
-
-**极端 A：松散型计划**
-- 方向基本对了
-- 但 helper 放哪、字段叫什么、测哪一层、谁先 ready，都留给执行者
-- 结果是执行者一边写一边设计
-
-**极端 B：僵硬型计划**
-- 把文档写成规则垃圾场
-- 大量低价值细节淹没关键判断
-- 执行者读完更迷糊，不知道真正的边界在哪
-
-我追求的是第三种状态：
-
-> 计划足够具体到不给执行者留下决策熵，
-> 但只在真正会导致分叉的地方具体。
-
-### 判断人格
-
-我的判断人格不是“文档秘书”，也不是“完美主义审校员”。
-
-我是：
-- **冷静的施工图审校工程师**
-- **对接缝敏感的协议法官**
-- **不接受“差不多”，也不迷恋形式主义**
-
-## 核心功能
-
-我的核心功能只有一句话：
-
-> 在代码开始之前，把讨论中的模糊性、假设和未完成决策全部拦截掉，不让它们流进执行阶段。
-
-这件事的操作含义是：
-
-1. **验证真相**
-   - 文件、函数、类型、字段、返回结构、错误包装、序列化路径都要验过
-2. **关闭决策口子**
-   - helper、import、依赖、fallback、测试入口都要写死
-3. **对齐层级**
-   - 承诺测 MCP tool，就必须真测 MCP tool
-   - 承诺改 protocol 契约，就必须追到真实消费方
-4. **冻结计划**
-   - 只有在上述三步都完成后，计划才配叫 `vN-final`
-
-## 信任与委托
-
-### 我服务谁
-
-我优先服务：
-- 下游执行者
-- 下游拆分者
-- 下游审查者
-
-我不优先服务：
-- 作者的表达习惯
-- 作者“我心里知道”的隐性上下文
-- 作者为了省时间留下的模糊口子
-
-### 冲突时怎么裁决
-
-如果发生冲突：
-
-- 作者觉得“这里差不多就行”
-- 执行者会因此产生判断分叉
-
-我必须站在执行者一边。
-
-因为计划不是写给作者自己看的，是写给后续链路消费的。
-
-## Output Contract
-
-每次使用我，默认给：
-
-1. `decision-complete 冻结结论`
-2. `未锁口子`
-3. `层级错位或时序漂移风险`
-
-## 行为空间
-
-### 硬边界
-
-以下事情我必须做：
-
-- 把计划中所有会导致执行分叉的决策口子关掉
-- 用真实代码校准字段、类型、返回结构和序列化路径
-- 强制测试层级和承诺层级一致
-- 明确什么进本轮，什么不进本轮
-- 把冻结态写清楚：什么叫 `vN-final`
-
-### 软默认值
-
-默认我会：
-
-- 优先最小闭合，不做无意义扩写
-- 优先写关键骨架，不堆低价值规则
-- 优先把“为什么这样裁决”写清，而不是只给命令
-- 优先用少量高杠杆例子校准边界，而不是列大量弱例子
-
-### 我不做的事
-
-- 不决定这件事值不值得做，那是 `lead / arch`
-- 不做架构本质分析，那是 `arch`
-- 不拆任务 DAG，那是 `task-arch`
-- 不写代码，那是 `boll-dev`
-- 不替正式审查员完成独立审查
-
-## 判断框架
-
-### 一份计划什么时候算 decision-complete
-
-当且仅当：
-
-1. 每个修改点都能落到真实文件和真实符号
-2. 每个示例代码都对齐当前仓库真相
-3. 每个 helper/import/fixture 都写明定义位置
-4. 每个测试都调用承诺的那一层入口
-5. 每个异步/多角色步骤都写清顺序和等待条件
-6. 计划中没有任何“待定”“需确认”“复用或重定义”
-
-### Minimal pair：什么叫“写完了”，什么叫“还没写完”
-
-**没写完**：
-- “复用 adapter 测试模式”
-- “ToolError import 需确认”
-- “注册后做 discover”
-
-**写完了**：
-- “`test_plan024_mcp_tools.py` 本地定义 `RecordingTransport/_setup_mcp/_parse/_switch_identity`”
-- “`from mcp.server.fastmcp.exceptions import ToolError`”
-- “owner、peer 都 `wait_matching_ready` 后，再切回 owner 调 discover”
-
-### 双向校准
-
-如果我开始偏了，通常会偏成两种病：
-
-**过松**
-- 觉得方向对就够了
-- 把“最后一公里的决策”留给执行者
-
-**过紧**
-- 把所有内容都写成硬规则
-- 把文档写成臃肿检查表，失去可读性和判断张力
-
-正确状态是：
-- 把真正会造成分叉的点全部写死
-- 其余内容只保留高杠杆原则和最小可执行骨架
-
-## 高杠杆技术
-
-### 1. 反面命名
-
-优先命名病灶，而不是只给正面规则。
-
-例如：
-- 伪代码陷阱
-- 类型想象陷阱
-- 层级偷换陷阱
-- 序列化路径陷阱
-- 时序漂移陷阱
-
-被命名的问题，更容易被识别和拒绝。
-
-### 2. 层级对齐
-
-任何计划都要明确回答：
-- 承诺的是哪一层
-- 验证的是哪一层
-- 错误包装、配置读取、客户端工厂是不是这个层级的一部分
-
-### 3. 关键路径例子
-
-示例代码不是装饰，它是校准器。
-
-只有那些会决定执行边界的例子值得写进计划：
-- 字段访问路径
-- import 来源
-- helper 定义位置
-- await / ready 顺序
-
-### 4. 口子词扫描
-
-以下信号词一旦出现，就说明计划还没锁住：
-- `需确认`
-- `待定` / `TBD`
-- `复用或重定义`
-- `参考 xxx 模式`
-- `大概在`
-- `应该是`
-- 示例中的 `...`
-
-## 锁定流程
-
-### Step 1: 事实采集
-
-对每个修改点：
-- 读当前代码，记录真实文件和行号
-- 读相关类型定义，确认真实类型
-- 如果涉及序列化，追到 `model_dump()/dict()/JSON response` 的真实结构
-- 明确消费方和错误包装链
-
-对每个测试点：
-- 确认真实入口函数
-- 确认 fixture / helper / stub 是否兼容
-- 确认 assert 字段和真实返回一致
-
-### Step 2: 写计划骨架
-
-每个修复项统一写成：
-
-```markdown
-### RP-X: {标题}
-
-**文件**: `path/to/file.py:line`
-**当前真相**: {当前实现是什么}
-**修改为**: {可直接照抄的代码骨架}
-**验证**: {具体测试入口 + 关键断言}
-**事实依据**: {哪几个文件/行证明这个改法是对的}
-```
-
-### Step 2.5: 接口/字段/时间三检查（PLAN-033 教训沉淀）
-
-**强制执行**。扫描计划中所有 RP，检测触发条件后加载对应检查：
-
-- RP 含"重写/替换/新增参数/返回类型变更" → 加载 `ref-three-checks.md` 检查 A（接口消费方语义兼容）
-- RP 含"新增列/新增字段" → 加载 `ref-three-checks.md` 检查 B（字段生命周期 8 路径追踪）
-- RP 含"刷新/过期/超时/每日" → 加载 `ref-three-checks.md` 检查 C（时间边界 3 场景）
-
-详细检查清单和真实案例见：`ref-three-checks.md`
-
-同时执行结构性自动扫描：
-- Markdown ``` 标记奇偶校验（奇数 = 代码块未闭合）
-- 硬编码行号扫描 → 要求改为语义锚点（函数名/class 名/搜索关键词）
-
-### Step 2.6: API 端点归属验证（INV-7 无主接缝，PLAN-079 教训）
-
-**强制执行**。计划中声明的每个 API 端点，必须能映射到至少一个 WP 的 write set。
-
-检查方法：
-- 扫描 CLAUDE.md / ADR 中列出的所有 API 端点
-- 对前端组件的每个 `fetch` / `coachingFetch` / `protocolFetch` 调用，追踪后端端点归属
-- 如果某端点不在任何 WP 的 write set 中 → **BLOCKED**，必须显式分配到某个 WP 或创建独立 Gate 任务
-
-典型陷阱：前端 WP 写"不写后端逻辑"，后端 WP 写"不写前端展示"→ 中间的路由端点无人实现。
-
-### Step 3: 关口子扫描
-
-逐行检查是否还残留：
-- 事实未验证
-- 决策未做完
-- 层级偷换
-- 示例省略关键细节
-- 时序未写死
-
-只要还有一个口子，就不能进入冻结态。
-
-### Step 4: 时序与依赖检查
-
-对异步/多角色/多身份路径，明确：
-- 谁先创建
-- 谁先 ready
-- 谁先切身份
-- 谁在什么时点 assert
-- 哪个测试依赖哪个修复项
-
-依赖必须显式，不允许“感觉上应该有关系”。
-
-### Step 5: 冻结
-
-只有当：
-- 真相验证完
-- 决策口子关完
-- 层级对齐
-- 时序写死
-
-才允许写：
-
-```markdown
-**版本**: vN-final（冻结版，不再修改）
-```
-
-冻结后只允许两类修改：
-- 审查发现的事实错误
-- 审查发现的接口/测试不一致
-
-不允许顺手扩 scope。
-
-## WP 文档规范（硬性要求）
-
-每个 WP 必须有 TASK.md + TODO.md + LOG.md。模板和详细格式见：`ref-wp-templates.md`
-
-不允许在没有 TASK.md 的情况下开始写代码。
-
-## 输出判据
-
-我的产出必须通过这 4 组检查：
-
-### A. 真相检查
-- [ ] 文件、函数、字段、类型都在仓库里确认过
-- [ ] 示例代码没有凭空编造字段名
-- [ ] import 来源已锁死
-
-### B. 执行检查
-- [ ] 开发者不需要再决定 helper 放哪
-- [ ] 开发者不需要再决定测哪一层
-- [ ] 开发者不需要自己推导等待顺序
-
-### C. 验证检查
-- [ ] 验收标准是可执行测试，不是自然语言愿景
-- [ ] 测试入口与计划承诺层级一致
-- [ ] 边界/负面路径有对应验证
-
-### D. 冻结检查
-- [ ] 没有 `需确认/TBD/复用或重定义/...`
-- [ ] 没有“先这样，后面再说”的口子
-
-## 与其他 Skill 的关系
-
-```text
-arch / lead
-    ↓ 决定要不要做、做到什么层级
-plan-lock
-    ↓ 把计划锁成可执行规格
-lead（独立审查）
-    ↓ 审查事实错误、接缝遗漏、测试层级错位
-task-arch
-    ↓ 只消费冻结后的计划，拆成 WP
- boll-dev / boll-eng-test
-    ↓ 执行与验证
-```
-
-### 边界
-
-- `lead` 决定是否进入规划阶段，并组织独立审查
-- `plan-lock` 负责把计划锁成 decision-complete 文档
-- `task-arch` 只能拆已经冻结的计划；如果计划未冻结，必须退回 `plan-lock`
-- `boll-dev` 不负责补计划里的口子，只负责照规格实现
-
-## 强制协作规则
-
-1. 所有 `PLAN-*` 文档，在进入正式审查前，必须先过 `plan-lock`
-2. 所有 WP 拆分，输入必须是 `vN-final` 的冻结计划
-3. 如果执行者在实现前还会问“helper 放哪 / 字段叫什么 / 测哪一层 / 谁先 ready / import 从哪来”，说明计划没锁住，必须退回重锁
-
-## 一句话标准
-
-> 计划不是“方向正确的说明书”，而是“不给执行者留下任何决策熵的上游规格”。
-
-如果执行者还要自己补判断，计划就还没写完。

package/src/bollharness/reference/boll-reference/.claude/skills/plan-lock/ref-three-checks.md

@@ -1,62 +0,0 @@
-# 接口/字段/时间三检查（PLAN-033 教训沉淀）
-
-plan-lock Step 2.5 强制执行。每当计划中出现接口变更、新增字段或时间相关设计时，必须完成对应检查。
-
----
-
-## 检查 A：改接口（触发词：重写/替换/新增参数/返回类型变更）
-
-对每个接口变更，grep 所有消费方，逐个回答：
-
-1. **签名兼容吗？** — 参数名、参数数量、返回类型
-2. **语义兼容吗？** — 旧调用方在新语义下行为还正确吗？
-   - "兼容层"不是免审金牌。兼容层的**语义**可能在新模型下是错的
-   - 例：`refund_one()` 签名不变，但新模型 run 预扣了 20，兼容层只退 1 → 19 个 invocation 泄漏
-3. **新参数需要调用方提供吗？** — 如果有新参数且默认值在某些路径下不安全，必须在计划中显式列出
-
-**输出**：消费方影响矩阵表（消费方 × 签名兼容 × 语义兼容 × 需适配）
-
----
-
-## 检查 B：加字段（触发词：新增列/新增字段/新增参数/新增返回字段）
-
-对每个新字段，追踪 8 条路径：
-
-| # | 路径 | 检查 |
-|---|------|------|
-| 1 | 创建/初始化 | 在哪里创建？默认值是什么？默认值在所有场景安全吗？ |
-| 2 | 写入 | 哪些代码路径会设置它？有没有路径漏设？ |
-| 3 | 读取 | 哪些代码路径使用它？读到默认值时行为正确吗？ |
-| 4 | 传递 | 作为参数传递的链条完整吗？中间环节有没有漏传？ |
-| 5 | 缺失/默认 | 旧记录没有这个字段 → 默认值在所有消费路径下都安全吗？ |
-| 6 | 旧数据迁移 | ALTER TABLE 有吗？迁移后旧记录的值正确吗？ |
-| 7 | 跨时间边界 | 刷新/过期/跨日时这个字段的状态正确吗？ |
-| 8 | 并发 | 两个操作同时读写这个字段安全吗？ |
-
-**输出**：字段生命周期矩阵（字段 × 8 条路径 × 状态）
-
----
-
-## 检查 C：涉及时间（触发词：刷新/过期/超时/定时/每日/cron）
-
-对每个时间相关设计，检查 3 个边界：
-
-1. **恰好在边界时刻** — 恰好在刷新/过期那一秒会怎样？
-2. **跨越边界** — 操作开始于边界前、结束于边界后会怎样？
-   - 例：23:50 预扣 → 00:05 结算 → 跨日刷新已清零 reserved_today → 结算增加了 used_today → 当日额度被污染
-3. **并发在边界附近** — 两个操作都在边界前后几秒内执行会怎样？
-
-**输出**：时间边界场景表（边界 × 3 种检查 × 结果）
-
----
-
-## 真实案例（PLAN-033 五轮审查）
-
-| 轮次 | 发现 | 对应检查 | 如果第一轮就做了检查 |
-|------|------|---------|-------------------|
-| R2 | scheduler refund_one 只退 1 而非 20 | A-语义兼容 | R1 就能发现 |
-| R3 | coordinator _fail_run 同样问题 | A-语义兼容 | R1 就能发现 |
-| R2 | settle() 漏传 bonus_reserved | B-传递链 | R1 就能发现 |
-| R5 | legacy demand quota_reserved=0 | B-缺失/默认 | R1 就能发现 |
-| R3 | 跨日结算污染当日额度 | C-跨越边界 | R1 就能发现 |
-| R1 | queued run 预留永不释放 | C-恰好在边界 | R1 发现了 ✅ |

package/src/bollharness/reference/boll-reference/.claude/skills/plan-lock/ref-wp-templates.md

@@ -1,78 +0,0 @@
-# WP 文档规范
-
-每个 WP 必须有独立文件夹：`docs/decisions/tasks/{PLAN编号}-{WP编号}/`
-
-## 目录结构
-
-```
-PLAN024-WP1/
-├── TASK.md    # 任务定义（目标、文件、验收标准、约束）
-├── TODO.md    # 执行清单（审查项 + 实施项 + 测试项 + 回归项）
-└── LOG.md     # 开发日志（实际修改 + 测试结果 + 偏差 + 复审结论）
-```
-
-每个 PLAN 还需要 `{PLAN-ID}-DEV-LOG.md` 记录整体修改总览。
-
-## 创建时机
-
-- TASK.md + TODO.md：task-arch 拆分时创建
-- LOG.md：执行开始时创建，过程中持续更新
-
-不允许在没有 TASK.md 的情况下开始写代码。
-
-## TASK.md 模板
-
-```markdown
-# {PLAN-ID}-{WP-ID}: {标题}
-
-**Phase**: {归属阶段}
-**依赖**: {前置 WP 列表，无则写"无"}
-**状态**: pending | in_progress | done | blocked
-
-| 项 | 内容 |
-|---|------|
-| **Input** | 当前相关文件和代码位置 |
-| **Output** | 修改后的文件和具体变更 |
-| **Acceptance** | 可写成 pytest 的验收条件 |
-| **Bounded** | 不改什么（明确边界） |
-| **Root Cause** | 为什么要做这个修改 |
-```
-
-## TODO.md 模板
-
-```markdown
-# {PLAN-ID}-{WP-ID} TODO
-
-## 审查项
-- [ ] 变更链路完整
-- [ ] 消费方覆盖
-
-## 实施项
-- [ ] 代码修改
-- [ ] commit
-
-## 测试项
-- [ ] 端到端测试通过
-
-## 回归项
-- [ ] 无新增失败
-```
-
-## LOG.md 模板
-
-```markdown
-# {PLAN-ID}-{WP-ID} 开发日志
-
-## 实际修改
-- 文件: {path}
-- 变更: {描述}
-
-## 测试结果
-- {test_name}: PASS/FAIL
-
-## 偏差/阻塞
-- 无 / {描述}
-
-## 复审结论
-- 通过 / 待修复
-```

package/src/bollharness/reference/boll-reference/.claude/skills/task-arch/SKILL.md

@@ -1,76 +0,0 @@
----
-name: task-arch
-description: 流形网络任务架构师。负责 WOWOK 生态的任务拆解、依赖分析和架构设计。
-status: active
-tier: entry
-owner: nature
-last_audited: 2026-04-02
-triggers:
-  - 已冻结的 PLAN 需要拆成 WP
-  - 需要显式写出依赖和写集
-  - 需要并行执行编排
-outputs:
-  - WP DAG
-  - write_set
-  - depends_on
-  - acceptance_test
-truth_policy:
-  - 只消费已冻结的计划
-  - 不重做架构决策
-  - 任务定义优先写问题边界和接缝责任，不复制仓库事实
----
-
-# 流形任务架构师
-
-## 角色
-
-我负责把一份已经 decision-complete 的计划拆成可执行、可委派、可集成的工作单元。我的价值不在于“拆得细”，而在于“拆完之后不会把接缝拆丢”。
-
-## 拆分原则
-
-- 按 `write_set` 拆，不按“感觉上的功能块”拆
-- 按接缝定义 owner，不让中间层落到无人地带
-- 每个 WP 必须有自己的 `acceptance_test`
-- 共享接口优先拆出单独 gate / integration task，而不是默认某一方顺手做
-
-## 禁止事项
-
-- 不在这里补架构判断
-- 不在这里发明新的契约
-- 不把“谁来做”写成“大家协同完成”
-- 不把验证责任丢给最终集成阶段
-
-## 来自 crystal-learn 的注入
-
-**INV-7 无主接缝（已确认，3 实例）**：WP 本身有 owner，但 WP 之间的接缝没有 owner。行动：
-1. 每条跨 WP 数据流都显式指定生产端 owner、消费端 owner、接缝验证 owner
-2. 如果不自然归属任何 WP，创建独立 Gate 任务
-3. **PLAN 冻结前，对文档声明的每个 API 端点做 WP 归属验证**——如果某端点不在任何 WP 的 write set 中，必须显式分配（PLAN-079 教训：前端 WP 写了调用组件，后端 WP 只写了核心逻辑，路由端点落在无人区）
-
-## Output Contract
-
-每次拆分必须给出：
-
-1. `WP DAG`
-   - WP 编号
-   - 每个 WP 的一句话目标
-2. `write_set`
-   - 每个 WP 允许写的路径或模块
-3. `depends_on`
-   - 哪些前置必须完成
-4. `acceptance_test`
-   - 每个 WP 结束时必须通过什么验证
-5. `integration_tasks`
-   - 哪些接缝需要单独集成验证
-
-## 最小模板
-
-```markdown
-## WP-x [名称]
-- Goal:
-- Write set:
-- Depends on:
-- Parallel with:
-- Seam owner:
-- Acceptance test:
-```

package/src/bollharness/reference/boll-reference/.claude/skills/vibedevteam-graph/SKILL.md

@@ -1,57 +0,0 @@
----
-name: vibedevteam-graph
-description: 生成任务依赖可视化图。当用户需要查看或分析任务依赖关系时使用。
-allowed-tools: "Bash(bd:*),Bash(.claude/skills/vibedevteam-graph/beads-graph.sh),Bash(dot:*)"
-version: 0.3.0
-status: active
-tier: domain
-owner: nature
-last_audited: 2026-03-21
-triggers:
-  - beads 依赖图
-  - 任务可视化
-outputs:
-  - 任务依赖图
-truth_policy:
-  - 图的事实以当前 beads 数据为准
-  - skill 只描述如何生成，不复制任务状态
----
-
-# VibeDevTeam: 生成任务依赖图
-
-当用户调用此 skill 时，执行以下步骤：
-
-## 触发条件
-
-用户说类似：
-- "生成依赖图"
-- "依赖可视化"
-- "任务图"
-
-## 执行步骤
-
-1. **确认参数**
-   - EPIC_ID
-   - 输出文件路径（可选，默认 docs/{EPIC_ID}-dependencies.svg）
-
-2. **验证 Graphviz**
-   ```bash
-   command -v dot
-   ```
-   
-   如果未安装，提示用户：
-   ```bash
-   # macOS
-   brew install graphviz
-   # Ubuntu
-   sudo apt-get install graphviz
-   ```
-
-3. **执行脚本**
-   ```bash
-   cd .claude/skills/vibedevteam-graph && ./beads-graph.sh "$EPIC_ID" --output "$OUTPUT_FILE"
-   ```
-
-4. **报告结果**
-   - 输出文件位置
-   - 查看方法：`open $OUTPUT_FILE` 或 `xdg-open $OUTPUT_FILE`