@bolloon/bolloon-agent 0.1.0

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

@@ -0,0 +1,26 @@
+---
+name: boll-animation
+description: 流形前端动画设计专才。决定动画该不该存在、该怎么动，遵循功能性动画哲学。
+status: archived
+tier: domain
+owner: nature
+last_audited: 2026-03-21
+triggers:
+  - 历史追溯
+outputs:
+  - 历史范围
+  - 失效原因
+  - replacement skills
+truth_policy:
+  - 当前 boll 不再从此 skill 获取活体判断
+replacement_skills:
+  - nature-designer
+---
+
+# Archived: boll-animation
+
+- 历史范围：boll 前端动画专才的旧版提示词。
+- 失效原因：当前动画与视觉判断统一收敛到 `nature-designer`，不再从这里分流。
+- Replacement skills：`nature-designer`
+
+完整历史内容保留在 git 历史中，不在当前文件继续维护。

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

@@ -0,0 +1,227 @@
+---
+name: boll-bridge
+description: boll bridge 专项工程 Skill。用于设计、诊断、实现、重构和修复 bridge 全链问题，包括 `bridge_agent/*`、`backend/product/bridge/*`、`backend/product/routes/bridge.py`、worker_distributed 执行链、Claude CLI 运行时、systemd 部署、事件/产物/complete 状态、线上 bridge 观测与环境一致性。当用户提到 bridge、hosted negotiation 卡死、completed 伪装、Claude CLI `code=1`、lease/heartbeat/events/complete、bridge 部署、bridge 测试、bridge 重构，或任何“本地可以、服务器偶尔不行”的 bridge 问题时使用。
+status: active
+tier: domain
+owner: nature
+last_audited: 2026-03-21
+triggers:
+  - bridge 故障
+  - bridge 重构
+  - bridge 同系统验证
+outputs:
+  - 当前主线
+  - 最新风险
+  - 验证结果
+  - source drift
+truth_policy:
+  - 先看真实失败证据，再解释代码机制
+  - bridge 运行时事实以生产证据和同系统验证为准
+  - 不引用 archived V1 specialist 作为默认升级路径
+---
+
+# boll Bridge
+
+## Mission
+
+把 bridge 当成一个跨环境、跨进程、跨协议的执行系统来处理，不当成单个脚本来修。
+
+优先级固定如下：
+
+1. 真相先于猜测
+2. 契约先于补丁
+3. 同系统验证先于服务器碰运气
+4. 终态正确性先于“看起来跑完了”
+
+## Tension Map
+
+每次处理 bridge 问题，都用下面 4 组张力校准：
+
+- **止血速度 vs 问题闭环**
+  判断函数：优先做最小但能关掉整类故障的修复，不做只改变表象的补丁。
+  过度：为了重构拒绝止血。
+  不足：为了止血继续复制字符串规则和隐式状态。
+
+- **本地信心 vs 生产真相**
+  判断函数：生产故障先看生产证据，再把故障变成可本地复现的同系统测试。
+  过度：一上来 SSH 看日志，不补本地闭环。
+  不足：不看失败 run 的真实 stderr/事件，只看代码猜原因。
+
+- **观测性 vs 噪声**
+  判断函数：只采能解释 run 命运的数据，至少覆盖 run_id、lease_id、compute_node、exit_code、stderr 摘要、artifact verdict、complete 结果。
+  过度：把原始 stdout 全量塞进所有通道。
+  不足：只能靠 journalctl 和 DB 手查。
+
+- **补丁 vs 重构**
+  判断函数：如果问题来自共享契约缺失、状态语义混淆、跨层重复逻辑，就进入设计/PLAN 路线；如果是局部实现偏差且不会再开新口子，才走快速修复。
+  过度：什么都上升为大重构。
+  不足：结构病连续三次还当单点 bug 修。
+
+判断人格：像事故指挥官和协议工程师的结合体。先锁证据，再切断风险，再把系统变得更可证明。
+
+## Workflow
+
+### 1. 锁定入口
+
+先判断当前请求属于哪一类：
+
+- **生产故障**：线上卡死、伪成功、偶发失败、服务器与本地不一致
+- **结构返工**：同类 bridge bug 反复出现，需要拆契约/拆模块
+- **运行时硬化**：Claude CLI、systemd、权限、网络、认证、目录、并发实例
+- **观测性建设**：管理后台、事件流、stdout/stderr、bridge 状态
+- **小修复**：局部 bug，且满足 lead 的快速通道条件
+
+如果不是小修复，默认按 `lead` 的 Gate 0-8 走，不直接写代码。
+
+### 2. 先读真相源
+
+默认先读这些路径：
+
+- `bridge_agent/agent.py`
+- `bridge_agent/config.yaml`
+- `bridge_agent/config.production.yaml`
+- `bridge_agent/deploy/RUNBOOK.md`
+- `bridge_agent/deploy/boll-bridge@.service`
+- `backend/product/routes/bridge.py`
+- `backend/product/bridge/service.py`
+
+如果是历史反复问题，再补读：
+
+- `docs/issues/008-production-hosted-negotiation-blockers-2026-03-18.md`
+- `docs/issues/009-bridge-observability-gap-2026-03-18.md`
+- `docs/issues/011-mcp-e2e-audit-2026-03-19.md`
+- [references/bridge-failure-taxonomy.md](references/bridge-failure-taxonomy.md)
+- [references/bridge-validation-ladder.md](references/bridge-validation-ladder.md)
+
+### 3. 生产故障先看证据
+
+遇到线上问题，强制按这个顺序：
+
+1. 取失败 run 的实际证据：状态、事件、stderr、exit code、complete 是否发出
+2. 对比同路径成功 case
+3. 核实环境差异：`claude_bin`、`HOME`、`CLAUDE_CONFIG_DIR`、systemd、网络、并发实例、远端 backend
+4. 最后才回代码解释机制
+
+禁止以下反模式：
+
+- 用代码审查冒充故障排查
+- 不看失败证据就改实现
+- 假设本地 shell 和 systemd runtime 一样
+- 把“代码还能写得更好”误判成“这就是本次故障根因”
+
+### 4. 给问题归层
+
+把问题明确归到以下一层或多层接缝，不要笼统说“bridge 坏了”：
+
+- **控制面契约**：`accept / heartbeat / events / complete / lease ownership`
+- **执行面运行时**：Claude CLI、OAuth、PATH、filesystem、tmp、network、systemd
+- **产物契约**：plan/delivery、placeholder、artifact identity、verdict
+- **事件语义**：哪些 phase 必须发，哪些 event 是终态前提
+- **状态语义**：`running / failed / done / completed_with_errors`
+- **测试闭环**：本地是否真的覆盖了线上正在跑的那条链
+
+如果故障跨了两层，优先把接缝定义出来，再决定改哪边。
+
+### 5. 决定走补丁还是设计路线
+
+走快速补丁前，必须同时满足：
+
+- 改动不涉及新的 bridge 语义
+- 不新增字符串约定或重复判定逻辑
+- 不改变本地/生产边界
+- 能用现有测试和一条新增验证证明不会复发
+
+只要出现以下任一情况，就进入设计/PLAN 路线：
+
+- 新增或修改 run 终态语义
+- 新增或修改 artifact verdict 语义
+- 新增或修改关键 bridge event 语义
+- 同类问题已经反复出现
+
+### 6. 部署边界声明（ADR-030 #26）
+
+部署 bridge 时必须声明完整文件清单，不依赖记忆挑文件：
+
+- `agent.py` 的隐式路径依赖（如 `assemble_prompts.py`、`prompts/`）必须在部署脚本中显式列出
+- 使用 `deploy.sh` 全量同步，不做手动 scp 增量
+- 部署后必须触发一个真实 run 验证 CLI 能完整执行，不是只检查"服务能启动"
+- `.env` 永远不覆盖，只手动编辑
+
+教训来源：ISSUE-022（bridge 节点缺少 assemble_prompts.py + prompts/ 导致所有协商 code=1 失败）
+- 本地与生产执行链不一致
+- 需要新增 prod-like 验证门禁
+
+## Bridge 不变量（来自 crystal-learn）
+
+**INV-2 格式断崖**：跨系统流程每一段独立看都对，但在衔接处格式或语义断裂。bridge 天然跨三个系统（本地 CLI → 新加坡 agent → 阿里云 backend），每一段有自己的输入输出假设。**行动**：逐步追踪数据流——这一步的 Content-Type / key / value 是什么？下一步期望什么？不要用"应该能对上"代替实际检查。
+
+**INV-4 约定耦合**：两个代码位置通过隐式字符串约定耦合（placeholder 模式、artifact 类型、event 类型），改一边另一边静默失效。Bridge 是这类问题的结构性热点——`phase`、`event_type`、`artifact_type` 等字符串在 agent.py 和 backend 路由中各自维护。**行动**：新增或修改 bridge 语义时，grep 该字符串在所有相关文件中的出现，确认两端一致。
+
+---
+
+## Engineering Rules
+
+### Contract Rules
+
+- 把 placeholder、artifact verdict、run outcome 定义成共享契约，不要散落在多个 `startswith` 判断里。
+- 把“执行器退出码”“产物是否真实”“run 最终状态”分开表示，不要互相冒充。
+- 把关键事件映射收口到单一转换层，不要让 phase -> event_type 的逻辑散在多个分支。
+- 把运行时配置和 deploy 文件当代码审查，不把它们当“运维附件”。
+
+### Refactor Bias
+
+优先拆成清晰职责面，而不是继续放大 `bridge_agent/agent.py`：
+
+- poll/lease
+- task materialization
+- executor runtime
+- output parsing
+- artifact verdict
+- reporter/complete
+
+如果一处判断需要在两处以上同步修改，默认说明这里缺共享契约。
+
+### Testing Rules
+
+- 不接受“只测 backend route，不测本地 worker 边界”作为 bridge 关闭条件。
+- 不接受“只测本地脚本，不测 `/api/bridge/*` 回写路径”作为 bridge 关闭条件。
+- 任何 bridge 终态相关改动，都必须证明：
+  - 非零退出码不会伪装成成功
+  - complete 失败不会永久挂 run
+  - placeholder 不会被当成真实交付
+  - 关键事件至少能支撑观测和终态判定
+
+## Deployment Boundary 声明
+
+部署 bridge 变更时必须声明：
+1. **原子单元**：哪些文件必须一起部署（不能只传一半）
+2. **路由验证**：新增/变更的路由清单，部署后必须 curl 验证
+3. **回滚点**：如果失败，回滚到哪个状态
+
+## Delivery Contract
+
+完成 bridge 任务后，先给这 4 块：
+
+1. 当前主线：本次改动锁住了哪条 bridge 问题
+2. 最新风险：还有哪些接缝未关闭
+3. 验证结果：本地 / prod-like / production 各自过了什么，没过什么
+4. Source drift：文档、代码、生产配置之间是否存在口径漂移
+
+如果是生产故障类任务，必须显式说明：
+
+- 看到的真实错误是什么
+- 本地是如何复现或替代验证的
+- 为什么这次不是只修表象
+
+## Escalation
+
+bridge 问题默认不要只在一个 skill 内硬扛。按问题性质联动：
+
+- 用 `lead` 管 Gate 0-8 和文档闭环
+- 用 `arch` 做跨边界契约和模块拆分
+- 用 `boll-eng-test` 设计同系统验证链
+- 用 `boll-dev` 做实现
+- 用 `boll-eng` 处理并行接缝和执行编排
+- 用 `soul-writing` 处理 Claude CLI / prompt / parser 相关行为文本
+
+当用户只是要“查清楚 bridge 为什么反复出问题”，先做诊断和分层，不直接给补丁。

package/src/bollharness/reference/boll-reference/.claude/skills/boll-bridge/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "boll Bridge"
+  short_description: "boll bridge design, repair, and runtime engineering"
+  default_prompt: "Use $boll-bridge to diagnose, design, implement, or repair a boll bridge issue end to end."

package/src/bollharness/reference/boll-reference/.claude/skills/boll-bridge/references/bridge-failure-taxonomy.md

@@ -0,0 +1,142 @@
+# Bridge Failure Taxonomy
+
+## Purpose
+
+用这份表快速判断 bridge 问题属于哪一类结构病，而不是把所有症状都叫成“bridge 不稳定”。
+
+## Surface Map
+
+boll bridge 不是单模块，而是一条跨边界执行链：
+
+1. backend `worker_distributed` run 被创建
+2. `/api/bridge/accept` 发 lease
+3. local bridge materialize task
+4. Claude CLI / subprocess 执行
+5. stdout / output files / bridge_output 被解析
+6. `/api/bridge/events` 推进观测链
+7. `/api/bridge/complete` 写终态和 artifacts
+
+任何一步失真，最终都可能表现为“偶尔成功、偶尔失败、偶尔卡住”。
+
+## Recurring Failure Classes
+
+### 1. Verdict Drift
+
+典型症状：
+
+- 失败 run 被标成 `completed`
+- placeholder delivery 被当成真实结果
+- 非零退出码和真实 plan/delivery 关系不清
+
+结构原因：
+
+- placeholder 生成和检测不共用契约
+- artifact verdict 在多处重复实现
+- run final status 缺少明确中间态
+
+优先检查：
+
+- `bridge_agent/agent.py`
+- fallback artifact 生成逻辑
+- artifact truthiness / has_real_artifacts 逻辑
+- backend result serialization
+
+### 2. Event Chain Break
+
+典型症状：
+
+- run 卡在 `running`
+- 某阶段明明完成了但前端看不到
+- `complete` 没发出或发出后状态没落地
+
+结构原因：
+
+- phase -> event_type 映射散落
+- 关键事件没有强制断言
+- complete 和 heartbeat 失败路径不统一
+
+优先检查：
+
+- `bridge_agent/agent.py`
+- `backend/product/routes/bridge.py`
+- `backend/product/bridge/service.py`
+- run events / ws / admin SSE 的接缝
+
+### 3. Runtime Parity Break
+
+典型症状：
+
+- 本地能跑，服务器 `code=1`
+- SSH 手跑成功，systemd 失败
+- OAuth / PATH / HOME / TMP 在生产下不稳定
+
+结构原因：
+
+- 本地 shell 与 systemd runtime 不一致
+- CLI 登录态、配置目录、权限边界没有进验证链
+- 把 deploy 文件当文档，不当代码
+
+优先检查：
+
+- `bridge_agent/config*.yaml`
+- `bridge_agent/deploy/boll-bridge@.service`
+- `bridge_agent/deploy/RUNBOOK.md`
+- journalctl 中的真实 stderr
+
+### 4. Control Plane Drift
+
+典型症状：
+
+- lease ownership mismatch
+- accept/heartbeat/complete 偶发 403/400
+- 多实例并发下 run 被重复处理或长时间无人处理
+
+结构原因：
+
+- lease、compute_node、status 契约不一致
+- 边界条件只在一端验证
+- 并发模型和观测模型脱节
+
+优先检查：
+
+- `backend/product/bridge/service.py`
+- `backend/product/routes/bridge.py`
+- DB lease / status / heartbeat 字段
+
+### 5. Test Illusion
+
+典型症状：
+
+- 本地测试全绿，线上首跑才发现主链断了
+- 测了 route，但没测 worker
+- 测了 CLI 局部逻辑，但没测远端 complete 路径
+
+结构原因：
+
+- 测试只覆盖片段，不覆盖同一系统
+- 线上正在跑的边界没有本地等价验证
+- 把“mock E2E”当真实 release gate
+
+优先检查：
+
+- 现有测试到底跳过了哪条边
+- 是否有 local same-system integration
+- 是否有 prod-like runtime smoke
+
+## Anti-Patterns
+
+- 用字符串模板充当状态机
+- 在 3 处复制 verdict 逻辑再靠人同步
+- 生产第一次发现问题，本地之后才补测试
+- 线上靠 SSH 调试，本地没有稳定复现路径
+- 把“偶发”当运气问题，不把变量清单列出来
+
+## First Questions
+
+每次进入 bridge 故障，先回答：
+
+1. 失败发生在 accept、execute、report 还是 complete？
+2. 失败 run 的 exit code、stderr、event timeline 是什么？
+3. 成功 case 和失败 case 的环境差异是什么？
+4. 当前问题属于 verdict drift、event chain break、runtime parity break、control plane drift 还是 test illusion？
+5. 这次修复是在关掉故障类别，还是只改一个文案和分支？

package/src/bollharness/reference/boll-reference/.claude/skills/boll-bridge/references/bridge-validation-ladder.md

@@ -0,0 +1,107 @@
+# Bridge Validation Ladder
+
+## Principle
+
+把上线当确认，不当调试。
+
+任何 bridge 改动都尽量沿这条梯子往上走。不能跳过某一层时，要显式说明为什么跳过，以及风险留在哪。
+
+## Level 0: Pure Logic
+
+适用：
+
+- 文件分类
+- placeholder / verdict
+- phase -> event 映射
+- config 解析
+
+要求：
+
+- 为纯函数补单元测试
+- 把历史 bug 变成固定回归样例
+
+## Level 1: Local Process
+
+适用：
+
+- subprocess 生命周期
+- stdout/stderr 捕获
+- timeout / retry / output scan
+
+要求：
+
+- 真起本地 subprocess
+- 验证非零退出、超时、输出文件扫描
+
+注意：
+
+- 这层还没覆盖 `/api/bridge/*`
+- 这层通过不代表 worker 主链通过
+
+## Level 2: Local Same-System Integration
+
+这是 bridge 最缺的一层，也是默认新增测试的优先位置。
+
+目标：
+
+- 在本地启动 test backend
+- 用真实 bridge worker 跑 `accept -> heartbeat/events -> complete`
+- 验证终态、artifacts、events、status 一致
+
+至少覆盖：
+
+- success
+- executor non-zero exit
+- complete failure fallback
+- placeholder 不会伪装成真实 delivery
+
+这层允许对 executor 做受控替身，但不允许跳过 bridge worker 本身。
+
+## Level 3: Prod-Like Runtime Smoke
+
+目标：
+
+- 验证 systemd / runtime / Claude CLI 这一层不是隐形变量
+
+至少核实：
+
+- `claude_bin`
+- `HOME`
+- `CLAUDE_CONFIG_DIR`
+- auth status / token freshness
+- repo_root / workdir / tmp 权限
+- backend base_url 可达
+
+这层可以是手工 smoke，但必须留下证据，不要只口头说“服务器上试过了”。
+
+## Level 4: Single-Instance Canary
+
+目标：
+
+- 用 1 个 bridge 实例验证真实生产链
+- 把生产当最终确认，不把多实例变量一起混进来
+
+要求：
+
+- 明确 run_id
+- 留下事件时间线
+- 验证 result/status/inbox 等下游语义
+
+## Level 5: Multi-Instance Rollout
+
+只有在前四层都足够扎实时再做。
+
+重点看：
+
+- accept 抢单一致性
+- compute_node 观测
+- 长时间无 complete 的告警
+- 并发下的 lease 与状态 freshness
+
+## Release Checklist
+
+- 是否存在本地可重复验证，而不是只能去服务器碰运气？
+- 是否明确区分了 executor exit、artifact verdict、run final status？
+- 是否验证了失败路径，而不是只验证成功路径？
+- 是否记录了哪些验证没做，以及为什么没做？
+- 是否把新教训沉淀回 skill / reference，而不是只写在一次性回复里？