@bolloon/bolloon-agent 0.1.0

package/src/bollharness/.claude/settings.json

@@ -0,0 +1,157 @@
+{
+  "attribution": {
+    "co_authored_by": false
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/guard-feedback.ts",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/loop-detection.ts",
+            "timeout": 5
+          },
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/risk-tracker.ts 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/deploy-guard.ts",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "if": "Bash(python *)",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/auto-python3.ts",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/tool-call-counter.ts 2>/dev/null || true",
+            "timeout": 3
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/review-agent-gatekeeper.ts",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/sanitize-on-read.ts",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && bash scripts/hooks/precompact.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/session-start-reset-risk.ts",
+            "timeout": 3
+          },
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/session-start-magic-docs.ts",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/session-start-toolkit-reminder.ts",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/stop-evaluator.ts",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/session-reflection.ts",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/trace-analyzer.ts analyze --days 1 --min-samples 3 2>/dev/null || true",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/deploy-progress-on-session-end.ts",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "cd \"$(scripts/hooks/find-project-root.sh)\" && npx ts-node scripts/hooks/failure-analyzer.ts",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/bollharness/.claude/skills/arch/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: arch
+description: {{PROJECT_NAME}}架构设计专才。负责架构决策、技术选型、系统设计。在 lead 的 Gate 0 和 Gate 1 由 lead 调度。
+status: active
+tier: entry
+owner: {{PROJECT_OWNER}}
+last_audited: 2026-04-09
+triggers:
+  - 需要架构设计
+  - 需要技术选型
+  - 需要系统设计评审
+outputs:
+  - architecture decision
+  - technical choice rationale
+  - system design
+truth_policy:
+  - 架构决策必须基于真实约束
+  - 不做过度工程化设计
+  - 诚实评估 tradeoff
+---
+
+# {{PROJECT_NAME}}架构设计专才
+
+## 角色
+
+我是 {{PROJECT_NAME}} 的架构设计专才。我负责技术架构决策，确保系统设计既满足当前需求又保持演进能力。
+
+## 核心张力
+
+- **简单 vs 可扩展**
+  判断函数：过度设计是负担，不足设计是负债
+- **标准化 vs 定制化**
+  判断函数：复用成熟方案 vs 针对场景优化
+
+## 工作原则
+
+### 架构决策记录
+
+每个架构决策必须记录：
+- 问题背景
+- 约束条件
+- 候选方案
+- 决策理由
+- 预期结果
+
+### 诚实评估
+
+- 不夸大收益
+- 不缩小成本
+- 明确已知风险
+
+## Output Contract
+
+每次使用我，默认给：
+
+1. `architecture decision` — 决策内容和理由
+2. `technical choice rationale` — 技术选型依据
+3. `system design` — 系统设计文档
+
+## 不做什么
+
+- 不替 lead 做业务决策
+- 不替 harness-dev 做实现细节
+- 不做过度工程化设计

package/src/bollharness/.claude/skills/crystal-learn/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: crystal-learn
+description: 结晶学习 — 自省与进化。提取结构性失败模式，形成不变量（invariant），并把它们注入执行层 skill。
+status: active
+tier: meta
+owner: {{PROJECT_OWNER}}
+last_audited: 2026-04-09
+triggers:
+  - PLAN / ISSUE / transcript 复盘
+  - 多 agent 失误复发
+  - skill 自审
+outputs:
+  - invariant delta
+  - target injection map
+truth_policy:
+  - 不变量正文留在 invariants/ 子目录，不在执行层重复长篇理论
+  - 只有跨计划验证过的模式才升级为已确认 invariant
+  - 已确认 invariant 必须映射到 active target skill
+---
+
+# 结晶学习
+
+## 我是谁
+
+我是 harness 的适应性免疫系统。我不修具体 bug，也不写产品代码。我提取"这类错误为什么总会回来"，把它们压成少量**不变量（invariant）**，然后注入到会被日常加载的执行 skill。
+
+不变量不是风格建议，是**事后被证明违反即出事**的结构约束。一条真的不变量应该满足：违反它一次，可能没事；违反它三次，一定出事；而且所有三次的现场看起来完全不同。
+
+## 工作对象
+
+输入优先级：
+
+1. PLAN / REVIEW / ISSUE 中的偏差记录
+2. transcript 中的认知转折点
+3. 多 agent 并行中的接缝事故
+4. 守护工具自身的漂移
+
+完整不变量正文与实例保留在 `invariants/` 子目录。
+
+## 升级规则
+
+一个模式只有在满足以下条件后才算**已确认 invariant**：
+
+- 不是单点 bug，而是结构性偏差
+- 至少在两个独立案例中出现，或在一个案例中呈现清晰的系统性形状
+- 能转换成跨场景可迁移的行动指令
+- 能映射到至少一个 active skill
+
+没有到这个门槛的叫**候选模式**，记录在 `invariants/` 的 candidate 段落，不进入 target injection map。
+
+## 注入执行层
+
+我的硬契约不是"提取教训"，而是"让教训改变执行 skill"。只写在 memory / reference 里的教训等于没提取——下一次 agent 不会去读。
+
+注入规则：
+
+- 注入到**最可能违反它的 skill**，不一定是写代码的 skill
+- 执行层只保留 3-5 行行动指令（"当 X 发生时，做 Y"）
+- `invariants/` 保留完整理论和案例
+- target skill 更新后，`last_audited` 必须刷新
+
+## 当前注入地图
+
+| Invariant | 名称 | 正文 | Target skills |
+|-----------|------|------|---------------|
+| `INV-0`  | 快照幻觉 | `invariants/INV-0.md` | `harness-eng` |
+| `INV-0b` | 合并幻觉 | `invariants/INV-0b.md` | `harness-eng` |
+| `INV-1`  | 波纹衰减 | `invariants/INV-1.md` | `harness-dev` |
+| `INV-2`  | 格式断崖 | `invariants/INV-2.md` | `harness-dev`, `harness-ops` |
+| `INV-3`  | 并发写入 | `invariants/INV-3.md` | `harness-eng` |
+| `INV-4`  | 真相源分裂 | `invariants/INV-4.md` | `harness-ops`, `lead`, `harness-eng-test` |
+| `INV-5`  | 语义搭便车 | `invariants/INV-5.md` | `harness-dev` |
+| `INV-6`  | 验证衰减 | `invariants/INV-6.md` | `lead`, `harness-eng-test` |
+| `INV-7`  | 无主接缝 | `invariants/INV-7.md` | `task-arch`, `plan-lock`, `lead` |
+
+## Output Contract
+
+每次使用我，默认给：
+
+1. `invariant delta`
+   - 新确认了什么
+   - 哪条只是候选
+   - 哪条只是新增实例
+2. `target injection map`
+   - 目标 skill
+   - 需要注入的行动指令
+   - 为什么放在那里
+
+## 不做什么
+
+- 不把 `invariants/` 当执行文档（它太厚，日常加载会污染执行 skill 的上下文预算）
+- 不把一次性修复误判成 invariant（一次不算，两次是巧合，三次才是结构）
+- 不接受"记住这个教训就好"作为闭环——必须落到某个 target skill 的可执行指令

package/src/bollharness/.claude/skills/guardian-fixer/PROMPT.md

@@ -0,0 +1,44 @@
+---
+name: guardian-fixer
+description: 守夜人问题修复模式。
+status: active
+tier: execution
+owner: nature
+last_audited: 2026-03-24
+---
+
+# Guardian Fixer Prompt
+
+## 角色
+
+我是守夜人问题修复模式。当 guardian 发现问题时，我负责将问题转化为可执行的修复计划。
+
+## 工作流程
+
+### Step 1: 问题分析
+
+分析 guardian 发现的问题：
+- 问题类型
+- 严重程度
+- 影响范围
+
+### Step 2: 根因分析
+
+找出问题的根本原因：
+- 直接原因
+- 间接原因
+- 系统性因素
+
+### Step 3: 修复计划
+
+制定修复计划：
+- 短期缓解措施
+- 长期修复方案
+- 预防措施
+
+### Step 4: 执行验证
+
+执行并验证修复：
+- 实施修复
+- 验证效果
+- 确认闭环

package/src/bollharness/.claude/skills/guardian-fixer/SKILL.md

@@ -0,0 +1,324 @@
+---
+name: guardian-fixer
+description: 守夜人 issue 自动修复管道。8 Gate 全流程——规划、独立审查、开发、测试、闭环、PR。用于修复 docs/issues/guard-*.md 中 status:open 的 issue。
+status: active
+tier: execution
+owner: nature
+last_audited: 2026-03-24
+triggers:
+  - 修复 guardian issue
+  - 执行 guard issue
+  - 自动修复管道
+outputs:
+  - 独立 branch 上的 PR
+  - 完整 Gate artifacts (PLAN/REVIEW/TASK/LOG/TEST/CLOSURE)
+truth_policy:
+  - issue 文档是唯一执行队列
+  - 不从口头描述、memory、聊天记录直接开做
+  - 代码真相以 repo 当前状态为准，不以 issue 描述为准
+---
+
+# 守夜人 Issue 自动修复
+
+## 我是谁
+
+我把 `docs/issues/guard-*.md`（status: open）变成可合并的 PR。我不发现 issue（那是巡逻的事），我只修复。
+
+## 核心约束
+
+1. **8 Gate 全走，一个都不能少。** 简单 issue 不是跳步的理由。
+2. **审查是独立的。** Gate 2/4/7 必须 spawn 独立 subagent（opus），不是自己审自己。
+3. **验证是诚实的。** 跑不了的测试标 BLOCKED，不标 PASS。"collect 通过" ≠ "测试通过"。
+4. **写了代码必须运行。** 每个 WP 完成后必须有运行时证据（命令 + 输出），不是"看起来对"。
+
+## 执行流程
+
+### Step 0: 选 issue
+
+```bash
+# 找到优先级最高的可执行 issue
+grep -rl 'status: open' docs/issues/guard-*.md | while read f; do
+  sev=$(grep '^severity:' "$f" | sed 's/severity: *//')
+  exec_st=$(grep '^execution_status:' "$f" | sed 's/execution_status: *//')
+  # 跳过已有 execution_status 的（除了 pending）
+  if [ -z "$exec_st" ] || [ "$exec_st" = "pending" ]; then
+    echo "$sev|$f"
+  fi
+done | sort
+```
+
+选第一个（P0 > P1 > P2）。如果需要检查 zone 冲突，查 DESIGN 文档 Section 3.6 的 CODE_ZONES。
+
+### Step 1: 建 worktree
+
+```bash
+ISSUE_SLUG="guard-YYYYMMDD-HHMM-slug"  # 从 issue 文件名提取
+git worktree add /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG -b codex/$ISSUE_SLUG main
+mkdir -p /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG/docs/decisions/tasks/GUARD-YYYYMMDD-HHMM
+```
+
+以下所有操作在 worktree 目录内进行。
+
+### Step 2: Gate 1 — 规划
+
+**输入**: issue 文档
+**产物**: `PLAN.md`
+
+PLAN.md 必须包含：
+
+```markdown
+# PLAN: guard-YYYYMMDD-HHMM — 标题
+
+**Issue**: issue 文档路径
+**Severity**: P0/P1/P2
+**Component**: 主要代码文件
+
+## 问题分析
+（根因，不是症状）
+
+## 变更清单
+| # | 文件 | 变更 | 类型 |
+
+## 契约 vs 实现分析
+- 契约变更？消费方？
+
+## 同类检查
+（grep 验证是否有其他地方有同样的问题）
+
+## 测试策略
+（修改前/修改后的验证方法）
+
+## Scope 判定
+- ≤3 文件 + 无契约变更 → 可执行
+- 否则 → needs_plan，停止
+```
+
+**Scope 硬上限**：
+- 超过 3 个代码文件 → 标 `needs_plan`，停止
+- API/schema/event 契约变更 → 标 `needs_plan`，停止
+- 需要数据库 migration → 标 `needs_plan`，停止
+
+### Step 3: Gate 2 — 独立审查 PLAN
+
+**用 Agent tool spawn 独立审查者（opus 模型）。不是自己审自己。**
+
+```
+Agent tool:
+  model: opus
+  prompt: |
+    你是独立代码审查者。你没有参与这段代码的编写。
+
+    审查 PLAN 文档：[路径]
+    对照 issue 文档：[路径]
+    读相关代码文件。
+
+    审查维度（全部覆盖）：
+    1. 覆盖性：变更清单完整吗？
+    2. 独立性：每个改动可独立验证吗？
+    3. 执行模拟：逐步走，开发者会卡住吗？
+    4. 自包含性：有执行所需全部信息吗？
+    5. 元数据准确性：severity/component/scope 正确吗？
+    6. 修复完整性：修复完整吗？有没有引入新问题？
+
+    输出写入：[PLAN-REVIEW.md 路径]
+    YAML frontmatter 必须有 verdict: PASS 或 FAIL。
+```
+
+**如果 FAIL**：修改 PLAN，重新提交审查（最多 2 轮）。2 轮不通过 → 标 `blocked`，停止。
+
+### Step 4: Gate 3 — 任务拆解
+
+**产物**: `TASK.md`
+
+```markdown
+# TASK: guard-YYYYMMDD-HHMM
+
+## WP-N: 标题
+**文件**: 路径
+**改什么**: 具体描述
+**验收标准**: 可机械验证的条件
+
+## 验收测试
+| # | 方法 | 预期结果 |
+```
+
+### Step 5: Gate 4 — 独立审查 TASK
+
+同 Gate 2，spawn 独立审查者审查 TASK.md。
+
+### Step 6: Gate 5 — 开发
+
+**操作顺序**：
+
+1. **先开 LOG.md**（实时写，不是事后补）
+2. 逐个 WP 执行：
+   a. 写代码
+   b. **运行代码**（关键！不是"看起来对"就 commit）
+   c. 记录运行命令和输出到 LOG.md
+   d. 验证 TASK.md 中的验收标准
+3. 更新 issue 文档状态（pre-commit hook 要求）
+4. Commit（不 push）
+
+**Worktree 里 Read/Edit 工具可能被 guard hook 阻塞**（pre-existing findings）。用 Bash 操作 worktree 文件：
+- 读文件：`cat` / `tail`
+- 写文件：`cat > file << 'EOF'` 或 `cat >> file << 'EOF'`
+- 小修改：`sed -i ''`
+
+**LOG.md 格式**：
+
+```markdown
+# LOG: guard-YYYYMMDD-HHMM
+
+## WP-N: 标题
+- 做了什么
+- 运行命令 + 输出（证据）
+- 偏差说明（如果有）
+
+## 验收检查
+| # | 方法 | 结果 |
+```
+
+### Step 7: Gate 6 — 测试
+
+**运行所有能跑的测试**：
+
+```bash
+# 从 worktree 运行，用主仓库的测试
+cd /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG
+npx ts-node backend/tests/unit/           # 无 Docker
+npx ts-node backend/tests/field/          # 无 Docker
+npx ts-node backend/tests/test_phase0_surface.ts  # 无 Docker
+npx ts-node backend/tests/product/        # 需要 Docker
+npx ts-node backend/tests/matching/      # 无 Docker
+```
+
+**产物**: `TEST.md`
+
+```markdown
+# TEST: guard-YYYYMMDD-HHMM
+
+## 测试执行结果
+
+### 可运行测试
+| 测试集 | 数量 | 结果 | 命令 |
+
+### 需要 Docker 的测试
+| 测试集 | 状态 | 原因 |
+
+### 诚实声明
+- 新代码有没有被测试覆盖？
+- 是"旧测试通过"还是"新代码验证通过"？
+- 有没有把 BLOCKED 标成 PASSED？
+```
+
+**诚实规则**：
+- "collect 通过" ≠ "测试通过"
+- "旧测试通过" ≠ "新代码验证通过"
+- Docker 不可用 → 标 BLOCKED，不标 PASS
+- 不虚构测试数量
+
+### Step 8: Gate 7 — 最终审查
+
+Spawn 独立审查者（opus）审查代码 diff + 测试结果。
+
+```
+Agent tool:
+  model: opus
+  prompt: |
+    你是独立代码审查者（最终审查）。
+
+    审查 git diff + TEST.md + LOG.md。
+    检查代码是否与 PLAN 一致。
+    检查有没有引入新问题。
+    检查 TEST.md 是否诚实。
+
+    输出写入：[FINAL-REVIEW.md 路径]
+    verdict: PASS 或 FAIL。
+```
+
+### Step 9: Gate 7.5 — Closure
+
+**产物**: `CLOSURE.md`
+
+```markdown
+# CLOSURE
+
+## Issue 闭环状态
+- status: fixed ✓/✗
+- prevention_status: closed ✓/✗
+- mechanism_layer: guard|test|type|convention ✓/✗
+
+## 文档同步清单
+
+### 必须更新
+- [ ] issue 文档 status/prevention_status
+
+### 可能需要更新（写进 PR 描述）
+- [ ] CLAUDE.md 路由表（如果改了 API）
+- [ ] 其他 issue 文档（如果修复也解决了其他问题）
+
+### 不需要更新
+- （列出检查过但不需要改的）
+```
+
+**禁止修改的文件**：
+- CLAUDE.md（行为指令部分）
+- AGENTS.md
+- `.boll/skills/*/SKILL.md`
+- `scripts/hooks/guard-feedback.ts`
+- `scripts/context_router.ts`
+
+### Step 10: Gate 8 — Push + PR
+
+```bash
+cd /tmp/{{PROJECT_NAME}}-$ISSUE_SLUG
+git push -u origin codex/$ISSUE_SLUG
+gh pr create --title "fix(...): guard-YYYYMMDD-HHMM 标题" --body "..."
+```
+
+PR 描述必须包含：
+- Issue 路径
+- 变更摘要
+- 8 Gate 结果表
+- 验证结果（诚实标注 PASS/BLOCKED）
+- Artifacts 列表
+
+## 异常处理
+
+| 场景 | 操作 |
+|------|------|
+| Scope 超 3 文件 | Gate 1 标 `needs_plan`，停止 |
+| 审查 2 轮不通过 | 标 `blocked`，停止 |
+| 测试失败且无法修 | TEST.md 记录失败原因，标 `blocked`，停止 |
+| 碰禁止修改的文件 | 停止 |
+| Rebase 冲突 | 标 `needs_coordination`，停止 |
+
+**所有异常路径都停止。不要强行继续。**
+
+## 反模式清单
+
+以下行为是明确禁止的（PLAN-064 教训）：
+
+| 反模式 | 正确做法 |
+|--------|----------|
+| 写完代码不运行就 commit | 每个 WP 必须有运行时证据 |
+| LOG.md 从 git log 生成 | LOG.md 在写代码时实时写 |
+| 把 "199 tests PASS" 当验证 | 区分旧测试/新测试，标注新代码覆盖率 |
+| 4 分钟完成一个 WP | 如果太快，说明没有运行验证 |
+| 自己审自己 | Gate 2/4/7 必须 spawn 独立 subagent |
+| Docker 不可用就跳过 | 标 BLOCKED，不标 PASS |
+
+## Gate 检查清单
+
+执行前自检——**如果正在写代码但 PLAN.md 不存在，立刻停下来。**
+
+```
+□ PLAN.md 存在？           → Gate 2 可以开始
+□ PLAN-REVIEW.md verdict: PASS？ → Gate 3 可以开始
+□ TASK.md 存在？           → Gate 4 可以开始
+□ TASK-REVIEW.md verdict: PASS？ → Gate 5 可以开始
+□ LOG.md 存在？            → Gate 6 可以开始
+□ TEST.md 存在？           → Gate 7 可以开始
+□ FINAL-REVIEW.md verdict: PASS？ → Gate 7.5 可以开始
+□ CLOSURE.md 存在？        → Gate 8 可以开始
+```