@bolloon/bolloon-agent 0.1.0

package/src/bollharness/reference/boll-reference/scripts/hooks/.sanitize-report.json

@@ -0,0 +1,12 @@
+{
+  "mode": "strict",
+  "files_scanned": 14,
+  "totals": {
+    "SECRET": 0,
+    "TRADE_SECRET": 0,
+    "PII": 0,
+    "NETWORK": 0,
+    "PROTOCOL_INTERNAL": 0
+  },
+  "records": []
+}

package/src/bollharness/reference/boll-reference/scripts/hooks/find-boll-root.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Walks up from $PWD to find the boll repo root.
+# Identifies it by presence of BOTH CLAUDE.md and scripts/guard-feedback.py.
+# This handles nested git repos (e.g. boll-progress/) that would confuse
+# `git rev-parse --show-toplevel`.
+#
+# Prints the absolute path to stdout. Exits 1 if not found.
+set -e
+d="${PWD}"
+while [ "$d" != "/" ] && [ -n "$d" ]; do
+  if [ -f "$d/CLAUDE.md" ] && [ -f "$d/scripts/guard-feedback.py" ]; then
+    echo "$d"
+    exit 0
+  fi
+  d="$(dirname "$d")"
+done
+# Fallback: check if CLAUDE_PROJECT_DIR is set by Claude Code
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ] && [ -f "${CLAUDE_PROJECT_DIR}/scripts/guard-feedback.py" ]; then
+  echo "${CLAUDE_PROJECT_DIR}"
+  exit 0
+fi
+# Final hardcoded fallback (this machine)
+if [ -f "/Users/nature/个人项目/boll/scripts/guard-feedback.py" ]; then
+  echo "/Users/nature/个人项目/boll"
+  exit 0
+fi
+exit 1

package/src/bollharness/reference/boll-reference/scripts/hooks/precompact.sh

@@ -0,0 +1,57 @@
+#!/bin/bash
+# PreCompact hook: 注入必须在 context compaction 中保留的关键信息
+# [来源: ADR-038 D2.3 + D9 (v4 Objective Recitation), CC PreCompact hook — exit 0 追加为 compact 指令]
+
+# 读取当前活跃的 PLAN/TASK/Issue 状态
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+
+cat <<'PRESERVE'
+## 必须保留的关键信息
+
+### 当前工作上下文
+- 保留当前正在进行的 PLAN/TASK/Issue 的完整状态和进度
+- 保留 Sprint Contract（如果有）的全部验收标准
+- 保留当前 WP 的 scope 和验收条件
+
+### 不可降级规则 (ADR-030 核心)
+- Guard > Memory: 能机械化检测的必须写 guard
+- 一个事实一个定义: 同一信息不得在多处重复定义
+- 验证看最后一公里: 验证必须到达用户可观测的终点
+
+### 行为约束
+- 所有 commit message 必须中英双语
+- 所有 subagent 必须使用 claude-opus-4-6
+- 不得跳过 Gate 2/4/6/8 审查
+- Issue 先于代码: 改代码前必须先创建 issue 文档
+PRESERVE
+
+# ── v4 D9: Objective Recitation ──
+# [来源: Manus/IMPACT — recite objectives at end of context after ~50 tool calls]
+# [来源: Cursor — 丢失 reasoning traces 导致 30% 性能下降]
+# 在 compact 后的新上下文末尾追加原始目标，防止注意力漂移。
+# KV cache 友好——只追加到末尾，不重排前文。
+PROGRESS_FILE="$REPO_ROOT/.boll/progress/current.json"
+if [ -f "$PROGRESS_FILE" ]; then
+    echo ""
+    echo "## Objective Recitation (v4 D9)"
+    echo ""
+    echo "**原始目标**（不可漂移，由 D8 Initializer Agent 写入后 read-only）："
+    python3 -c "
+import json, sys
+try:
+    data = json.load(open('$PROGRESS_FILE'))
+    print(f\"  {data.get('objective', '<未设置>')}\")
+    print()
+    pending = [f for f in data.get('features', []) if f.get('status') != 'passing']
+    if pending:
+        print('**未完成 features**：')
+        for f in pending:
+            print(f\"  - [{f.get('status', '?')}] {f.get('id', '?')}: {f.get('subject', '')}\")
+    else:
+        print('**所有 features 已 passing**，可以进入 Stop 流程。')
+except Exception as e:
+    print(f'  <progress.json 解析失败: {e}>')
+" 2>&1
+fi
+
+exit 0

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/schemas/metrics-jsonl-allowlist.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bollharness.dev/schemas/metrics-jsonl-allowlist.json",
+  "title": "bollharness metrics jsonl field allowlist",
+  "description": "Allowed top-level fields for every line in .boll/state/metrics/*.jsonl. scan_verify_artifacts.ts --metrics rejects any line containing a key not listed here. Tightening this allowlist is the primary defense against accidental PII / SECRET leakage via metrics sinks (v2 patch_4 / security P1#4).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["ts", "event"],
+  "properties": {
+    "ts": {
+      "description": "Event timestamp (ISO-8601 string or epoch-seconds number).",
+      "type": ["string", "number"]
+    },
+    "event": {
+      "description": "Short event name, e.g. guard_fired / hook_failed / rebaseline_required.",
+      "type": "string"
+    },
+    "stage": {
+      "description": "Claude Code hook stage (PreToolUse / PostToolUse / SessionStart / ...).",
+      "type": "string"
+    },
+    "tool": {
+      "description": "Tool name if applicable (Edit / Write / Bash / Task / ...).",
+      "type": "string"
+    },
+    "matcher": {
+      "description": "Hook matcher that routed the event.",
+      "type": "string"
+    },
+    "hook": {
+      "description": "Hook script basename (e.g. guard-feedback.ts).",
+      "type": "string"
+    },
+    "outcome": {
+      "description": "allow / block / warn / noop / error.",
+      "type": "string"
+    },
+    "exit_code": {
+      "type": "integer"
+    },
+    "duration_ms": {
+      "type": "number"
+    },
+    "file_path": {
+      "description": "Relative path of the edited / read file, if applicable.",
+      "type": "string"
+    },
+    "category": {
+      "description": "Sanitize category (SECRET / TRADE_SECRET / PII / NETWORK / PROTOCOL_INTERNAL).",
+      "type": "string"
+    },
+    "reason": {
+      "description": "Short human-readable reason; must not contain raw secret material.",
+      "type": "string"
+    },
+    "session_id": {
+      "description": "Claude Code session id.",
+      "type": "string"
+    },
+    "project_root": {
+      "type": "string"
+    },
+    "schema_version": {
+      "type": "string"
+    }
+  }
+}

package/src/bollharness/scripts/checks/next_decision_number.sh

@@ -0,0 +1,48 @@
+#!/bin/sh
+# 起草 ADR / PLAN 时给出下一个可用号（与 pre-commit numbering check 对齐）.
+#
+# 用法:
+#   scripts/checks/next_decision_number.sh ADR
+#   scripts/checks/next_decision_number.sh PLAN
+#
+# 来源: H 系列收尾 + Nature feedback "plan/adr 序号老是容易重复".
+
+set -e
+
+KIND="${1:-}"
+case "$KIND" in
+    ADR|PLAN) ;;
+    *)
+        echo "Usage: $0 {ADR|PLAN}" >&2
+        exit 2
+        ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+if [ -z "$REPO_ROOT" ]; then
+    echo "Not in a git repo." >&2
+    exit 2
+fi
+
+cd "$REPO_ROOT"
+
+DECISIONS_DIR="docs/decisions"
+if [ ! -d "$DECISIONS_DIR" ]; then
+    echo "No $DECISIONS_DIR/ found." >&2
+    exit 2
+fi
+
+# 取所有非 H 系列 ADR/PLAN-NNN 主号（剥落字母 sub-id），找最大值 +1
+MAX=$(ls "$DECISIONS_DIR" 2>/dev/null \
+    | grep -E "^${KIND}-[0-9]{3}[A-Z]?-" \
+    | grep -vE '^(ADR|PLAN)-H[0-9]+-' \
+    | sed -E "s/^${KIND}-([0-9]{3})[A-Z]?-.*/\1/" \
+    | sort -n | tail -1)
+
+if [ -z "$MAX" ]; then
+    NEXT=1
+else
+    NEXT=$((10#$MAX + 1))
+fi
+
+printf "%s-%03d\n" "$KIND" "$NEXT"

package/src/bollharness/scripts/ci/count-components.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# count-components.sh — WP-03 AC 1 primary judge + WP-SEC-1 meta-self-check.
+#
+# Emits three lines that WP-SEC-1 CI asserts against MANIFEST.yaml:
+#   command_instances=<N>   # count of "command": entries in .boll/settings.json
+#   unique_scripts=<N>      # deduped scripts referenced by those commands
+#   physical_files=<N>      # hook + root-script files on disk (L1 registry)
+#
+# Meta-self-check (§13.5 INV-4 activation 5):
+#   After set -e, the script verifies (a) its own file still exists, and
+#   (b) .github/workflows/ci.yml — if present — still references this script
+#   by name. If either check fails, exit 2 with the message
+#   "count-components.sh meta-self-check failed: the chokepoint itself is vapor".
+#
+# Run from repo root. Reads .boll/settings.json, scripts/hooks/, scripts/.
+
+set -e
+
+# --- meta-self-check ---------------------------------------------------------
+SELF_PATH="$(cd "$(dirname "$0")" && pwd)/$(basename "$0")"
+test -f "${SELF_PATH}" || {
+  echo "count-components.sh meta-self-check failed: the chokepoint itself is vapor" >&2
+  exit 2
+}
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+CI_WORKFLOW="${REPO_ROOT}/.github/workflows/ci.yml"
+if [ -f "${CI_WORKFLOW}" ] && ! grep -q 'count-components.sh' "${CI_WORKFLOW}"; then
+  echo "count-components.sh meta-self-check failed: the chokepoint itself is vapor" >&2
+  exit 2
+fi
+# -----------------------------------------------------------------------------
+
+cd "${REPO_ROOT}"
+
+# command_instances: every "command" key in settings.json's hooks[]
+# Count the total commands across all hook stages.
+if command -v jq >/dev/null 2>&1; then
+  CMD_INSTANCES=$(jq '[
+    .hooks.PreToolUse[]?.hooks[]?,
+    .hooks.PostToolUse[]?.hooks[]?,
+    .hooks.PreCompact[]?.hooks[]?,
+    .hooks.SessionStart[]?.hooks[]?,
+    .hooks.SessionEnd[]?.hooks[]?,
+    .hooks.Stop[]?.hooks[]?,
+    .hooks.PostToolUseFailure[]?.hooks[]?
+  ] | length' .boll/settings.json)
+else
+  # Fallback: line-grep. Less precise but works without jq.
+  CMD_INSTANCES=$(grep -c '"command":' .boll/settings.json || echo 0)
+fi
+
+# unique_scripts: distinct scripts referenced by those commands.
+# Extract the last `npx ts-node scripts/...` or `bash scripts/...` token and dedupe.
+UNIQUE_SCRIPTS=$(grep -oE '(npx ts-node|bash) scripts/[^ "]+' .boll/settings.json \
+  | awk '{print $2}' | sort -u | wc -l | tr -d ' ')
+
+# physical_files: hooks dir + 2 root scripts
+HOOKS_COUNT=$(ls scripts/hooks/*.ts scripts/hooks/*.sh scripts/hooks/*.md 2>/dev/null | wc -l | tr -d ' ')
+ROOT_COUNT=$(ls scripts/guard-feedback.ts scripts/deploy-guard.ts 2>/dev/null | wc -l | tr -d ' ')
+PHYSICAL=$((HOOKS_COUNT + ROOT_COUNT))
+
+echo "command_instances=${CMD_INSTANCES}"
+echo "unique_scripts=${UNIQUE_SCRIPTS}"
+echo "physical_files=${PHYSICAL}"

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`

package/src/bollharness/scripts/context-fragments/pi-agent-operations.md

@@ -0,0 +1,74 @@
+---
+paths:
+  - "src/agents/**"
+---
+
+# Pi Agent 操作与工具定义
+
+> 来源: pi-sdk.ts TOOL_DEFINITIONS + getDefaultResponse
+> 关联: src/agents/constraint-layer.ts（工具注册）
+
+---
+
+## 核心操作
+
+| 操作 | 描述 | 方法签名 |
+|------|------|----------|
+| 读取文档 | 读取并分析文档内容，支持 .txt, .md, .pdf, .docx | `read_document(path)` |
+| 总结文档 | 总结文档内容，可选提供上下文 | `summarize_document(path, context?)` |
+| 改进文档 | 改进文档，需提供文件路径和改进要求 | `improve_document(path, requirements)` |
+| 查看节点 | 查看已连接的对等节点 | `list_peers()` |
+| 发送消息 | 向指定对等节点发送消息 | `send_message(peer_id, message)` |
+| 广播消息 | 广播消息到所有节点 | `broadcast_message(message)` |
+| 查看身份 | 查看当前智能体身份 | `get_identity()` |
+| 设置 Persona | 更新智能体 persona 信息 | `set_persona(persona_json)` |
+| 执行工作流 | 执行预定义工作流 | `run_workflow(steps)` |
+| 查看日志 | 查看最近操作日志 | `get_operation_logs()` |
+
+---
+
+## 示例请求格式
+
+### 文档操作
+```
+"读取 README.md"
+"总结一下 src/index.ts"
+"改进文档，按照更清晰的错误处理要求"
+```
+
+### P2P 网络操作
+```
+"查看当前连接了哪些节点"
+"向 QmABC... 发送测试消息"
+"广播消息：系统将在 10 分钟后维护"
+```
+
+### 身份与状态
+```
+"查看身份"
+"查看日志"
+```
+
+---
+
+## 工具注册位置
+
+工具在 `pi-sdk.ts` 的 `PiAgent` 类构造函数中注册，映射到：
+- `src/agents/constraint-layer.ts` — ConstraintLayer 基类提供的基础能力
+- `src/network/p2p.ts` — P2P 网络模块
+- `src/documents/reader.ts` — 文档读取模块
+
+---
+
+## 自然语言指令映射
+
+| 自然语言指令 | 解析关键词 | 执行方法 |
+|-------------|-----------|----------|
+| 读取 X | `读取`、`read_document`、`read` | `readDocument(path)` |
+| 总结文档 | `总结`、`summarize_document` | `summarizeDocument(path, context?)` |
+| 改进文档 | `改进`、`improve_document` | `improveDocument(request)` |
+| 查看节点 | `查看节点`、`list_peers` | `listPeers()` |
+| 发送消息 | `向 X 发送消息`、`send_message` | `sendMessage(peerId, message)` |
+| 广播消息 | `广播消息`、`broadcast_message` | `broadcast(message)` |
+| 查看身份 | `查看身份`、`get_identity` | `getIdentity()` |
+| 查看日志 | `查看日志`、`get_operation_logs` | `getOperationLogs()` |

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

@@ -0,0 +1,15 @@
+## Protocol API 消费方
+
+你正在编辑 /protocol/ 相关代码。以下是 Protocol API 的消费方列表：
+
+| 消费方 | 入口 | 认证方式 |
+|--------|------|----------|
+| MCP Server (Python) | `mcp-server/boll_mcp/client.py` | session token |
+| MCP Server (Node) | `mcp-server-node/src/client.ts` | session token |
+| 前端 website | `website/` fetch 调用 | session token (cookie) |
+| Bridge Agent | `bridge_agent/` | bridge API key |
+| 外部 A2A 调用方 | federation endpoint | DID 签名 |
+
+**行为约束**: 修改任何 /protocol/ 路由的请求/响应结构时，必须检查上述所有消费方是否兼容。
+不得在不更新消费方的情况下修改返回字段名或删除字段。
+新增字段必须是 optional，避免破坏现有消费方。

package/src/bollharness/scripts/context-fragments/run-events-consumers.md

@@ -0,0 +1,15 @@
+## run_events 消费方（共享结构）
+
+你正在编辑 run_events 相关代码。此表有 6 个消费方，各自角色不同：
+
+| 消费方 | 读/写 | 用途 | 关键依赖 |
+|--------|-------|------|----------|
+| Bridge events 路由 | 写 | 接收 worker 上报的事件 | event_type 枚举 |
+| Catalyst coordinator | 写 | 记录协商轮次事件 | round_number, role |
+| Run status API | 读 | 前端展示进度 | 按 run_id 查询 + 时间排序 |
+| Run result API | 读 | 提取最终产物 | artifact 类型过滤 |
+| Admin event log | 读 | 运维审计 | 全字段 |
+| WebSocket hub | 读 | 实时推送 | 增量查询（last_id） |
+
+**行为约束**: 修改 run_events 表结构或写入逻辑时，必须逐一确认 6 个消费方不受影响。
+不得假设"只有一个地方读"。读模型截断会导致长 run 状态不正确。

package/src/bollharness/scripts/context-fragments/scene-fidelity.md

@@ -0,0 +1,13 @@
+## 场景保真度分级
+
+你正在编辑场景相关代码。每个场景有明确的保真度等级：
+
+| 等级 | 含义 | 数据来源 | 示例 |
+|------|------|----------|------|
+| **real** | 接真实 Protocol API | 生产后端 | startup-hub |
+| **demo** | 有独立后端但非协议链路 | demo 专用 API | ai-gig-market |
+| **shell** | 纯前端展示，无后端 | 静态/mock 数据 | 其他展示页 |
+
+**行为约束**: 文档和代码中声明的保真度必须与运行时实际行为一致。
+不得在文档中声称"真实协议"而代码跑 demo fallback（承诺 vs 现实漂移）。
+修改场景接入方式时，必须同步更新场景配置中的 fidelity 字段。

package/src/bollharness/scripts/context-fragments/truth-source-hierarchy.md

@@ -0,0 +1,15 @@
+## 真相源优先级
+
+你正在编辑核心文档。boll 的真相源有明确的优先级：
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | 运行中的代码 | 实际行为是最终真相 |
+| 2 | 数据库 schema + 测试 | 可执行的约束 |
+| 3 | ADR / TECH / PLAN 文档 | 设计决策记录 |
+| 4 | CLAUDE.md | 开发指导（派生自上层） |
+| 5 | MEMORY.md | 会话间记忆（最易过期） |
+
+**行为约束**: 当不同层级的信息冲突时，必须以高优先级来源为准并修正低优先级来源。
+CLAUDE.md 中的信息必须可以从代码或 ADR 中验证——不得包含无法溯源的断言。
+修改真相源文件时，必须检查下游是否需要同步更新。