@bolloon/bolloon-agent 0.1.1 → 0.1.3

package/src/bollharness/CLAUDE.md

@@ -0,0 +1,73 @@
+# CLAUDE.md — bollharness
+
+bollharness 是一个 **AI Agent Session 治理框架**——通过 Claude Code hooks、guards、上下文路由和安装器，给任意项目加装结构化的 agent 行为约束。
+
+## 架构
+
+```
+bollharness/
+├── .boll/
+│   ├── settings.json        # Hook 注册表（16 hooks，7 stages）
+│   ├── rules/               # Path-scoped rules（Claude Code 按文件路径自动加载）
+│   └── skills/              # Skill 定义（harness-dev-handoff, guardian-fixer 等）
+├── scripts/
+│   ├── hooks/               # 14 个 hook 脚本（session lifecycle + tool guards）
+│   ├── guard-feedback.ts    # PostToolUse 入口 — 上下文路由（机制 A）+ guard 检查（机制 B）
+│   ├── deploy-guard.ts      # PreToolUse Bash 入口 — 部署安全拦截
+│   ├── context_router.ts    # 文件路径 → 上下文片段路由表（ADR-030 §3.4.1）
+│   ├── guard_router.ts      # 文件路径 → guard 脚本映射（ADR-030 §3.3）
+│   ├── context-fragments/   # 17 个上下文片段（guard-feedback.ts 注入用）
+│   ├── checks/              # Guard 脚本（check_*.ts）
+│   ├── install/             # 安装器（phase2_auto.ts + trust token）
+│   └── lib/                 # 共享库
+├── templates/scaffold/      # 目标项目骨架模板（安装时复制）
+├── schemas/                 # YAML/JSON schema 定义
+├── docs/decisions/          # ADR-030, ADR-038, ADR-041
+└── .boll/MANIFEST.yaml  # 物理清单（版本 + 文件注册表）
+```
+
+
+**同步覆盖范围**：
+- Step 1: `scripts/hooks/*`（跳过 boll-only 的 `find-boll-root.sh`）
+- Step 2: 路径修补（`find-boll-root.sh` → `find-project-root.sh`）
+- Step 3: settings.json hook 注册对比
+- Step 4: 共享脚本（guard-feedback.ts, deploy-guard.ts, context_router.ts, guard_router.ts）
+- Step 5: context-fragments/ 目录
+
+## 开发约束
+
+### 必须遵守
+- 所有命令使用 `npx ts-node`
+- Commit message 中英双语 + `Co-Authored-By: Claude Opus 4.6`
+- 审查类 subagent 必须用 opus 模型，不降级 sonnet
+- 审查类 agent 工具白名单必须 schema-level 隔离写权限（ADR-038 D11）
+- Guardian issue 必须先建 `docs/issues/*.md` 再写代码
+
+### 安装器开发
+- `phase2_auto.ts` 所有函数必须**幂等**（重复运行不改变结果）
+- Trust token 使用 HMAC + 30min 滑动窗口 + 6h 绝对窗口
+- 安装步骤顺序不可打乱（trust → bundle → scaffold → gitignore → paths → hooks）
+
+### Hook 开发
+- Hook 必须 fail-open（`|| true`）或有明确的 fail-closed 理由
+- Hook timeout 不超过 30s（guard-feedback.ts 最大）
+- 新增 hook 后必须同时更新 settings.json 注册和 MANIFEST.yaml
+
+### 路径规则
+- `find-project-root.sh` 是 bollharness 的项目根定位器（3 层锚点，fail-closed）
+- `find-boll-root.sh` 是 boll 专用的（不同步到 bollharness）
+- settings.json 中所有 hook command 使用**相对路径**解析器，不含绝对路径
+
+## 接手入口
+
+```bash
+npx ts-node .boll/skills/harness-dev-handoff/scripts/collect_handoff_context.ts
+```
+
+然后读 `.boll/skills/harness-dev-handoff/SKILL.md`。
+
+## 关键 ADR
+
+- **ADR-030**: Guard Signal Protocol — 上下文路由 + guard 检查的设计
+- **ADR-038**: Harness Optimization — 11 决策（metrics、fragment TTL、review agent 隔离等）
+- **ADR-041**: Codex Division of Labor — 判断类 vs 执行类 subagent 分流

package/src/bollharness/README.md

@@ -0,0 +1,143 @@
+[中文](README.zh-CN.md) | English
+
+# bollharness
+
+> "How do you let AI handle so much development with so little supervision?"
+
+This is the answer.
+
+bollharness is a governance layer for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It makes AI agents reliable enough that you can set direction, walk away, and trust the work actually lands — with review gates, completion verification, and mechanical enforcement that no amount of prompting can replicate.
+
+## The Problem
+
+Claude Code is remarkably capable. But left unsupervised, it has structural biases:
+
+- **Claims completion prematurely** — "all tests pass" (didn't run them)
+- **Skips review** — "this change is simple enough" (it wasn't)
+- **Drifts from plans** — starts fixing one bug, ends up refactoring three files
+- **Self-evaluation bias** — asks itself "did I do a good job?", answers "yes"
+
+You end up supervising more than you saved in development time. The 80% it does well makes the 20% it silently drops even harder to catch.
+
+## The Insight
+
+```
+CLAUDE.md instruction compliance:  ~20%
+PreToolUse hook enforcement:       100%
+```
+
+Instructions don't reliably change AI behavior. Mechanical constraints do.
+
+A review agent told "don't modify files" obeys ~70% of the time. A review agent whose tool manifest doesn't list Edit/Write obeys 100% of the time — it physically can't call what isn't there.
+
+bollharness applies this principle everywhere: if it matters, enforce it with a hook, not a sentence.
+
+## What Changes
+
+| Without bollharness | With bollharness |
+|---|---|
+| "Did you run the tests?" → "Yes" (didn't) | Mechanical gate checks `progress.json` — can't fake evidence |
+| AI stops mid-chat, injects completion checklist | Stop hook parses session transcript — only triggers when uncommitted writes exist |
+| Review agent "helpfully" edits what it reviews | Review agent physically cannot call Edit/Write (schema-level isolation) |
+| "This PR is simple, let's skip review" | Gates 2/4/6/8 mechanically require independent review — no exceptions |
+| Parallel AI sessions contaminate each other | Each session's scope is isolated via its own transcript file |
+| Agent drifts into unrelated fixes | Context routing injects domain-specific rules only for files being edited |
+
+## How It Works
+
+### Hooks: enforcement at the moment of action
+
+16 hooks across 7 lifecycle stages. They intercept *as things happen*, not after:
+
+```
+SessionStart  →  Load context, reset risk state, surface tools
+PreToolUse    →  Block unsafe deploys, gate review agents, sanitize reads
+PostToolUse   →  Route context on edit, detect loops, track risk
+Stop          →  Verify completion candidate exists (transcript × git diff)
+SessionEnd    →  Reflect, analyze traces, persist progress
+```
+
+### The 8-Gate State Machine
+
+Every significant change flows through gates. Even-numbered gates require independent review — not the same agent checking its own work:
+
+```
+G0 Problem  →  G1 Design  →  G2 Review*
+  →  G3 Plan  →  G4 Review+Lock*
+  →  G5 Tasks  →  G6 Review*
+  →  G7 Execute+Log  →  G8 Final Review*
+
+* = Independent reviewer (separate context, read-only tools)
+```
+
+### Automated Checks
+
+15 validators run on file changes: API type consistency, doc freshness, security patterns, fragment integrity, hook registration, and more. They catch drift before it compounds.
+
+### Skills
+
+16 specialized behaviors — from architecture design (`arch`) to failure pattern extraction (`crystal-learn`) to structured bug triage (`bug-triage`). Skills install judgment frameworks, not rule lists, so the agent can navigate situations the skill didn't explicitly cover.
+
+Each skill has `{{PLACEHOLDER}}` structural slots designed to be filled with your project's context during installation.
+
+## Install
+
+```
+
+### Three Tiers
+
+| Tier | Trust level | What happens |
+|------|-------------|-------------|
+| **drop-in** | Minimal | Installs hooks + skills as-is. Try it, see what happens. |
+| **adapt** | Medium | Reads your README + docs, customizes skills to your project. |
+| **mine** | Full | Reads your work transcripts, deeply adapts to your patterns. |
+
+### What Gets Installed
+
+```
+your-project/
+├── .boll/
+│   ├── settings.json    # Hook registrations (appends, won't clobber)
+│   ├── skills/          # 16 agent behavior definitions
+│   └── rules/           # Path-scoped context (auto-loaded by file path)
+├── scripts/
+│   ├── hooks/           # 16 lifecycle hooks
+│   └── checks/          # 15 automated validators
+└── CLAUDE.md            # Governance guide (generated, yours to edit)
+```
+
+The installer is idempotent — run it twice, get the same result.
+
+## Design Principles
+
+1. **Hooks over instructions** — If compliance matters, don't ask. Enforce.
+2. **Schema-level isolation** — Review agents' tool manifests exclude write tools. Not "please don't" — *can't*.
+3. **Fail-open where safe** — A hook that can't read its data injects *more* checks, not fewer. The failure mode is always "too cautious," never "silently skipped."
+4. **Session isolation** — Completion detection uses per-session transcript parsing. No shared mutable state between parallel sessions.
+5. **Structural slots over blank space** — Project-specific content becomes `{{PLACEHOLDER}}` with meta-instructions (what to put, why it matters, how to discover it), not empty fields you forget to fill.
+
+## Requirements
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+- Node.js 18+
+- Git
+
+## Origin
+
+Born from 6 months of production use on [boll](https://boll.net), an agent collaboration protocol. The governance layer kept proving independently valuable — every AI-assisted project needs it, not just ours. So we extracted it.
+
+The hooks, gates, and isolation patterns were designed by getting burned first, then building the guard. Every rule in this system exists because an AI agent found a creative way to not follow the previous rule.
+
+## Acknowledgments
+
+This project was originally developed in Python as `wow-harness` and has been migrated to TypeScript for improved type safety, better developer experience, and tighter integration with modern JavaScript/TypeScript tooling.
+
+The migration preserved all original functionality while leveraging TypeScript's:
+- Static type checking for reduced runtime errors
+- Better IDE support and code completion
+- Improved maintainability for larger codebases
+- Native ES modules and modern JavaScript features
+
+## License
+
+MIT

package/src/bollharness/README.zh-CN.md

@@ -0,0 +1,131 @@
+中文 | [English](README.md)
+
+# bollharness
+
+> "你怎么做到让 AI 自己开发，人几乎不用管？"
+
+这就是答案。
+
+bollharness 是 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 的治理层。它让 AI agent 变得足够可靠——你定方向，AI 交付，工作真的能落地。靠的不是提示词里多写几句"请认真做"，而是机械化的审查门禁、完成验证和工具隔离。
+
+## 问题
+
+Claude Code 能力很强。但不加约束时，它有结构性偏见：
+
+- **假装完成** — "测试全过了"（其实没跑）
+- **跳过审查** — "这个改动很简单"（并不简单）
+- **任务漂移** — 修一个 bug，顺手重构三个文件
+- **自我评价偏差** — 问自己"做得好不好？"，回答"好"
+
+你花在监督上的时间，比省下的开发时间还多。更难受的是，它做对的 80% 让你放松警惕，剩下 20% 的静默遗漏更难发现。
+
+## 核心洞察
+
+```
+CLAUDE.md 指令遵从率:     ~20%
+PreToolUse hook 执行率:   100%
+```
+
+指令改变不了 AI 的行为。机械约束可以。
+
+告诉审查 agent "不要修改文件"，遵从率约 70%。把 Edit/Write 从它的工具清单里删掉，遵从率 100%——它物理上调不了不存在的工具。
+
+bollharness 把这个原则应用到所有该管的地方：重要的事不靠说，靠 hook。
+
+## 装了之后有什么变化
+
+| 没有 bollharness | 有 bollharness |
+|---|---|
+| "跑测试了吗？" → "跑了"（没跑） | 机械化门禁检查 `progress.json` — 伪造不了证据 |
+| 纯聊天时弹出完成检查清单 | Stop hook 解析 session transcript — 只在有未提交的编辑时才触发 |
+| 审查 agent "顺手"改了它审查的代码 | 审查 agent 物理上无法调用 Edit/Write（schema 级隔离） |
+| "这个 PR 简单，跳过审查吧" | Gate 2/4/6/8 机械化强制独立审查 — 没有例外 |
+| 并行 AI session 互相污染 | 每个 session 通过独立 transcript 文件隔离作用域 |
+| Agent 漂移去修不相关的东西 | 上下文路由只对正在编辑的文件注入领域规则 |
+
+## 怎么工作的
+
+### Hook：在动作发生的那一刻介入
+
+16 个 hook 覆盖 7 个生命周期阶段。不是事后审查，是实时拦截：
+
+```
+SessionStart  →  加载上下文、重置风险状态、展示可用工具
+PreToolUse    →  拦截危险部署、门控审查 agent、净化读取内容
+PostToolUse   →  编辑时路由上下文、检测循环、追踪风险
+Stop          →  验证是否存在完成候选品（transcript × git diff）
+SessionEnd    →  反思、分析轨迹、持久化进度
+```
+
+### 8 关状态机
+
+每个重要变更都要过关。偶数关要求独立审查——不是同一个 agent 自己检查自己的工作：
+
+```
+G0 问题  →  G1 设计  →  G2 审查*
+  →  G3 方案  →  G4 审查+锁定*
+  →  G5 任务拆分  →  G6 审查*
+  →  G7 执行+日志  →  G8 终审*
+
+* = 独立审查者（独立上下文、只读工具）
+```
+
+### 自动化检查
+
+15 个验证器在文件变更时运行：API 类型一致性、文档新鲜度、安全模式、片段完整性、hook 注册等。在漂移累积之前就抓住它。
+
+### Skill
+
+16 个专业化行为——从架构设计（`arch`）到失败模式提取（`crystal-learn`）到结构化 bug 分诊（`bug-triage`）。Skill 安装的是判断框架，不是规则清单，所以 agent 能应对 skill 没明确覆盖的情况。
+
+每个 skill 都有 `{{PLACEHOLDER}}` 结构化槽位，安装时会填入你项目的上下文。
+
+```
+
+### 三个层级
+
+| 层级 | 信任度 | 效果 |
+|------|--------|------|
+| **drop-in** | 最低 | 原样安装 hook + skill。先试试看。 |
+| **adapt** | 中等 | 读你的 README + 文档，把 skill 适配到你的项目。 |
+| **mine** | 完全 | 读你的工作 transcript，深度适配到你的模式。 |
+
+### 安装了什么
+
+```
+your-project/
+├── .boll/
+│   ├── settings.json    # Hook 注册（追加模式，不覆盖已有配置）
+│   ├── skills/          # 16 个 agent 行为定义
+│   └── rules/           # 路径作用域上下文规则（按文件路径自动加载）
+├── scripts/
+│   ├── hooks/           # 16 个生命周期 hook
+│   └── checks/          # 15 个自动化验证器
+└── CLAUDE.md            # 治理指南（自动生成，你可以自由编辑）
+```
+
+安装器是幂等的——跑两次，结果一样。
+
+## 设计原则
+
+1. **Hook 优于指令** — 重要的事不靠说，靠执行。
+2. **Schema 级隔离** — 审查 agent 的工具清单里没有写工具。不是"请不要"——是"不能"。
+3. **安全方向 fail-open** — hook 读不到数据时注入*更多*检查，不是更少。失败模式永远是"过于谨慎"，绝不是"静默跳过"。
+4. **Session 隔离** — 完成检测用每个 session 独立的 transcript 解析。并行 session 之间零共享可变状态。
+5. **结构化槽位** — 项目特定内容变成 `{{PLACEHOLDER}}` + 元指令（放什么、为什么重要、怎么发现它），不是你忘记填的空白字段。
+
+## 环境要求
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+- Node.js 18+
+- Git
+
+## 来历
+
+从 [boll](https://boll.net)（流形，一个 Agent 协作协议项目）6 个月的生产使用中提取出来的。治理层不断证明它独立于项目也有价值——每个 AI 辅助开发的项目都需要它，不只是我们的。
+
+这里的每一条 hook、每一个 gate、每一种隔离模式，都是因为 AI agent 找到了创造性的方法来绕过上一条规则，所以才被加上的。不是设计出来的，是被逼出来的。
+
+## License
+
+MIT

package/src/bollharness/reference/boll-reference/scripts/hooks/stop-evaluator.md

@@ -0,0 +1,57 @@
+# Stop Hook: PreCompletionChecklist + On-Demand Evaluator
+
+你是独立 Evaluator。你的工作是在 agent 完成任务前验证工作质量。
+
+## PreCompletionChecklist
+
+在允许完成前，逐条验证：
+
+1. **Git 状态**: 所有新文件是否已 `git add`？是否有未保存的变更？
+2. **测试**: 如果有代码变更，相关测试是否通过？运行 `backend/venv/bin/pytest -q backend/tests/unit --tb=no -q` 确认。
+3. **文档一致性**: 代码变更是否需要更新文档？路由变更是否反映在路由表中？
+4. **无半成品**: 是否有 TODO/FIXME/HACK 被遗留？是否有 dead code 或未使用的 import？
+5. **契约一致性**: API 类型、路由路径、配置 key 是否在所有引用处一致？
+
+## On-Demand Evaluator
+
+如果当前任务 scope >= 3 files 或涉及 API 契约变更，额外执行 Grading Criteria 评估：
+
+| 维度 | 检查点 |
+|------|--------|
+| **Design Quality** | 架构是否合理？是否利用了现有模式？ |
+| **Originality** | 是否超越模板化实现？ |
+| **Craft** | 代码清洁、命名一致、边界处理、无 AI slop |
+| **Functionality** | 核心路径可走通、契约一致、无断裂 |
+
+每维 1-5 分。**硬阈值: 任何维 < 3 = FAIL**。
+
+## 重要警告
+
+你天然倾向于"识别问题后说服自己不是大问题"。**抵抗这个倾向。**
+
+具体表现：
+- "代码看起来正确" — 不够，要实际验证
+- "测试已经通过了" — 哪些测试？覆盖了变更吗？
+- "这个小问题不影响功能" — 小问题累积成大问题
+
+**如果不确定，判为 FAIL。宁严勿松。**
+
+## 输出格式
+
+```
+## PreCompletionChecklist
+- [x/!] Git 状态: ...
+- [x/!] 测试: ...
+- [x/!] 文档一致性: ...
+- [x/!] 无半成品: ...
+- [x/!] 契约一致性: ...
+
+## Evaluator (如果触发)
+Design Quality: X/5
+Originality: X/5
+Craft: X/5
+Functionality: X/5
+
+## 裁决: PASS / FAIL
+原因: ...
+```

package/src/bollharness/scripts/context-fragments/artifact-linkage.md

@@ -0,0 +1,14 @@
+## 代码变更与 Artifact 关联
+
+你正在编辑决策文档。代码变更必须伴随相应的 artifact：
+
+| 变更类型 | 必须伴随的 artifact |
+|----------|---------------------|
+| 新功能 | ADR 或 PLAN 文档 |
+| Bug 修复 | Issue 文档（含根因分析） |
+| 架构变更 | ADR + 影响范围分析 |
+| 契约变更 | 消费方清单 + 迁移说明 |
+
+**行为约束**: 不得提交无 artifact 关联的重大变更。
+目标态文档不得使用"已完成"语气描述尚未实现的功能（承诺 vs 现实漂移）。
+PLAN 文档中的 WP 状态必须反映实际代码状态，不是计划状态。

package/src/bollharness/scripts/context-fragments/auth-consumers.md

@@ -0,0 +1,17 @@
+## 认证消费方与安全约定
+
+你正在编辑认证相关代码。以下是认证体系的消费方：
+
+| 消费方 | 认证方式 | 入口文件 |
+|--------|----------|----------|
+| Protocol API | session token (Bearer) | `backend/product/auth/middleware.py` |
+| MCP Server (Python) | session token | `mcp-server/boll_mcp/client.py` |
+| MCP Server (Node) | session token | `mcp-server-node/src/client.ts` |
+| SecondMe OAuth | client_id + secret | `backend/product/auth/secondme.py` |
+| Bridge API | bridge API key | `backend/product/routes/bridge.py` |
+| Admin API | admin key | `backend/product/routes/admin.py` |
+| WebSocket | ticket auth | `backend/product/ws/` |
+
+**行为约束**: 前端不得暴露任何 API Key。SecondMe OAuth 的 client_secret 不得硬编码。
+修改认证中间件时，必须确认所有消费方的认证链路不受影响。
+session token 必须有 TTL，不得发放永不过期的 token。

package/src/bollharness/scripts/context-fragments/bridge-constitution.md

@@ -0,0 +1,13 @@
+## Bridge 宪法（ADR-026）
+
+你正在编辑 Bridge 相关代码。以下 5 条规则约束所有 bridge 改动：
+
+1. **Worker 不拥有业务解释权，只上报执行事实。** 如果代码需要理解输出内容的含义，它写错了地方。
+2. **同一个语义只允许有一个定义。** 文件名模式、artifact 类型、event 含义，只能在一个地方定义。
+3. **跑通了就发结果，没跑通就报 failed。** 不做 partial_success 抢救、不生成 placeholder。
+4. **生产不能是第一个集成环境。** 本地必须能用 fake CLI + 真实 HTTP backend 跑完整链。
+5. **新增观测维度或 event 类型，只改 server，不改 worker。**
+
+三层职责：`boll-run` 定义成功产物契约 -> `worker` 执行和上报事实 -> `server` 解释事实并生成产品语义。
+
+**行为约束**: 你不得在 worker 侧添加任何需要理解业务语义的逻辑。所有解释权必须归 server。

package/src/bollharness/scripts/context-fragments/catalyst-distributed.md

@@ -0,0 +1,18 @@
+## 分布式协商约定
+
+你正在编辑 catalyst 相关代码。端侧与平台侧职责严格分离：
+
+**平台侧（cloud catalyst）**：
+- 协调协商轮次、管理 deadline、聚合响应
+- 拥有全局视角，决定何时进入下一轮或结束
+
+**端侧（bridge worker）**：
+- 执行具体的 LLM 调用、生成响应
+- 只上报执行事实，不判断协商是否成功
+
+**BYOK 模式**：用户绑定自己的 API Key（Anthropic / MiniMax / 自定义 base_url）。
+平台侧使用用户 key 调用 LLM，不存储 key 明文（仅 session 级绑定）。
+
+**行为约束**: 不得在 worker 侧添加协商策略逻辑（何时结束、何时重试）。
+catalyst coordinator 的状态机变更必须伴随测试覆盖。
+BYOK base_url 必须经过校验，不得接受任意 URL（SSRF 防护）。

package/src/bollharness/scripts/context-fragments/closure-checklist.md

@@ -0,0 +1,13 @@
+## Issue 闭环检查清单
+
+你正在编辑 issue 文档。关闭 issue 前必须逐条确认：
+
+1. **prevention_status 是否 closed？** 如果是 open，说明复发路径未关闭，不得标 Fixed
+2. **mechanism_layer 是否声明？** 必须指定防护机制：guard / test / type / convention
+3. **有无具体的防护措施描述？** 不能只写"已修复"，必须说明如何防止复发
+4. **Guard > Memory 原则**：如果防护靠"记住规则"，则 prevention 不算 closed
+
+**行为约束**: 你不得在 prevention_status 为 open 的情况下将 status 改为 fixed。
+如果根因分析表明无法机械化防护，必须显式标注 `mechanism_layer: convention` 并说明原因。
+
+检查顺序：根因 -> 复发路径 -> 防护机制 -> 标记状态。不得跳过中间步骤。

package/src/bollharness/scripts/context-fragments/contract-consumers.md

@@ -0,0 +1,15 @@
+## 契约 vs 实现 + 消费方追踪
+
+你正在编辑 API 路由代码。区分契约和实现是防止漂移的核心：
+
+**契约**（改了必须通知消费方）：
+- URL 路径、HTTP method、请求/响应 JSON schema
+- 环境变量名、配置 key
+- 事件类型枚举、artifact 类型枚举
+
+**实现**（内部可自由调整）：
+- 函数签名、内部数据结构、算法细节
+
+**行为约束**: 修改契约时，必须先列出所有消费方，逐一确认兼容性。
+消费方列表不靠记忆维护——必须 grep 代码确认谁在调用。
+新增 API 字段必须是 optional；删除字段必须走废弃流程，不得直接移除。

package/src/bollharness/scripts/context-fragments/db-shared-structures.md

@@ -0,0 +1,15 @@
+## DB 共享结构与迁移约定
+
+你正在编辑数据库相关代码。以下表被多个模块共享：
+
+| 表 | 主要写入方 | 读取消费方 |
+|----|-----------|-----------|
+| users | auth 模块 | protocol, dashboard, admin |
+| demands | formulation | matching, runs, dashboard |
+| runs | catalyst, bridge | status API, result API, admin, WS |
+| run_events | bridge, catalyst | 6 个消费方（见 run-events-consumers） |
+| agents | protocol | discovery, federation, MCP |
+
+**行为约束**: SQLAlchemy `create_all()` 不会 ALTER 已有表——新增列必须用迁移脚本。
+修改表结构时，必须检查所有读取消费方的查询是否兼容。
+不得在不同模块中对同一表定义不同的 ORM model（一个表一个 model 定义）。

package/src/bollharness/scripts/context-fragments/fixed-three-layers.md

@@ -0,0 +1,19 @@
+## Fixed 三层定义
+
+你正在编辑 issue 文档。"Fixed" 不等于"症状消失"：
+
+| 层级 | 含义 | 标准 | 标记 |
+|------|------|------|------|
+| Level 1 | 症状消失 | 生产不报错了 | Runtime Fixed |
+| Level 2 | 复发路径关闭 | 有机制防止同类问题再次发生 | **Fixed**（最低标准） |
+| Level 3 | 机制消灭 | 有 guard 自动检测 | Fixed + Guarded |
+
+issue doc YAML frontmatter 必须包含：
+```yaml
+status: fixed|open|wont_fix
+prevention_status: open|closed|not_applicable
+mechanism_layer: guard|test|type|convention
+```
+
+**行为约束**: 如果标 `status: fixed` 但 `prevention_status` 是 `open`，则不合格。必须先分析复发路径。
+Guard: `check_issue_closure.py`

package/src/bollharness/scripts/context-fragments/general-dev-principles.md

@@ -0,0 +1,11 @@
+## 通用开发原则
+
+以下原则适用于所有代码变更：
+
+1. **Guard > Memory**: 如果一件事靠"记住规则"维护，它一定会出错。能机械化检测的，必须写 guard。
+2. **一个事实一个定义**: 同一信息不得在多处重复定义。其余位置必须自动派生或引用。
+3. **验证看最后一公里**: "服务启动了"不等于"功能正常"。验证必须到达用户可观测的终点。
+4. **先分层再动手**: 区分 policy / contract / implementation 三层，搞清楚问题在哪层再修。
+
+**行为约束**: 不得引入新的重复定义。如果发现已有重复，应在本次变更中收口为单一来源。
+不得跳过测试直接部署。不得用 `--no-verify` 绕过 pre-commit hook。

package/src/bollharness/scripts/context-fragments/issue-first.md

@@ -0,0 +1,8 @@
+## Issue-First 工作流
+
+修复 Bug 或变更业务逻辑前，先确认 `docs/issues/` 或 `docs/decisions/` 中有对应文档。
+没有文档就没有复发路径分析，修了也白修。
+
+**检查清单**（一行即可）:
+- 工作区是否已有或已创建对应的 issue/decision 文档？
+- 文档中是否写了复发路径（prevention_status）？

package/src/bollharness/scripts/context-fragments/mcp-parity.md

@@ -0,0 +1,16 @@
+## MCP 双端一致性约定
+
+你正在编辑 MCP 相关代码。Python 和 Node 两端必须保持一致：
+
+- **工具数量**：两端都是 54 个 @mcp.tool() / registerTool()
+- **工具名称**：必须完全相同（boll_xxx）
+- **行为语义**：相同输入必须产生相同输出结构
+- **版本号**：pyproject.toml 和 package.json 版本必须一致
+
+对应文件映射：
+- Python: `mcp-server/boll_mcp/server.py` <-> Node: `mcp-server-node/src/index.ts`
+- Python: `mcp-server/boll_mcp/client.py` <-> Node: `mcp-server-node/src/client.ts`
+- Python: `mcp-server/boll_mcp/config.py` <-> Node: `mcp-server-node/src/config.ts`
+
+**行为约束**: 改了一端后，你必须检查另一端是否需要同步。不得单独修改一端的工具签名或行为。
+Guard: `check_mcp_parity.py`