@bolloon/bolloon-agent 0.1.0

package/src/bollharness/scripts/context-fragments/two-language.md

@@ -0,0 +1,15 @@
+## 两套语言体系
+
+你正在编辑面向用户的代码。协议术语和用户语言必须严格分离：
+
+**协议层**（仅开发者/文档可见）：
+formulation, crystallization, catalyst, nomination, intent field, operator, resonance
+
+**用户层**（UI/文案/帮助文本）：
+需求澄清, 多方协商, 协调, 推荐, 能力匹配
+
+**行为约束**: 前端 UI、用户提示、错误消息中不得出现协议内部术语。
+用户永远不需要知道"结晶"是什么——他们只知道"多方协商"。
+比喻：酒店管家不会跟客人说"我现在执行 housekeeping protocol"。
+
+禁词（用户可见文本）: "播种意图"、"共振"、"场域"、"结晶"等诗意表达。

package/src/bollharness/scripts/context-fragments/version-sources.md

@@ -0,0 +1,14 @@
+## 版本号来源清单
+
+你正在编辑版本相关文件。一个事实只允许有一个定义：
+
+| 版本号 | 权威来源 | 必须同步的位置 |
+|--------|----------|----------------|
+| MCP Python | `mcp-server/pyproject.toml` | CLAUDE.md 引用 |
+| MCP Node | `mcp-server-node/package.json` | 必须与 Python 版本一致 |
+| 后端 API | `backend/product/protocol/service.py` | /protocol 元数据返回 |
+| 前端 | `website/package.json` | 部署产物 BUILD_ID |
+
+**行为约束**: 修改任何版本号时，必须同步所有关联位置。
+Python MCP 和 Node MCP 版本号必须完全一致，不得出现 0.x.y vs 0.x.z 的漂移。
+"一个事实一个定义"——如果两个地方都写死版本号，其中一个必须是自动派生的。

package/src/bollharness/scripts/hooks/find-project-root.sh

@@ -0,0 +1,47 @@
+#!/bin/bash
+# Walks up from $PWD to find the bollharness-installed project root.
+#
+# Anchor priority:
+#   1. .bollharness/MANIFEST.yaml  (primary — declared by installer)
+#   2. CLAUDE.md                   (fallback — older projects or pre-install)
+#
+# Why not scripts/guard-feedback.ts like the old boll-specific script?
+# Because that created a circular dependency: guard-feedback.ts was both
+# the anchor AND the target invoked by the hook. Projects that don't ship
+# guard-feedback.ts (because they disabled it via issue-adapter.yaml) would
+# fail to locate their own root. The MANIFEST anchor is independent of any
+# specific hook installation.
+#
+# Prints absolute project root to stdout. Exits 1 if not found.
+set -e
+d="${PWD}"
+while [ "$d" != "/" ] && [ -n "$d" ]; do
+  if [ -f "$d/.bollharness/MANIFEST.yaml" ]; then
+    echo "$d"
+    exit 0
+  fi
+  d="$(dirname "$d")"
+done
+
+# Fallback 1: walk up again looking for CLAUDE.md alone
+d="${PWD}"
+while [ "$d" != "/" ] && [ -n "$d" ]; do
+  if [ -f "$d/CLAUDE.md" ]; then
+    echo "$d"
+    exit 0
+  fi
+  d="$(dirname "$d")"
+done
+
+# Fallback 2: CLAUDE_PROJECT_DIR env var set by Claude Code
+if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+  if [ -f "${CLAUDE_PROJECT_DIR}/.bollharness/MANIFEST.yaml" ] || [ -f "${CLAUDE_PROJECT_DIR}/CLAUDE.md" ]; then
+    echo "${CLAUDE_PROJECT_DIR}"
+    exit 0
+  fi
+fi
+
+# Fail-closed: no hardcoded machine-specific path. If you reach here the
+# project is either not yet installed or CLAUDE_PROJECT_DIR is unset —
+# both cases should surface as an error to the hook caller.
+exit 1

package/src/bollharness/scripts/hooks/inbox-poll.sh

@@ -0,0 +1,78 @@
+#!/bin/bash
+# H9 inbox poll：状态检查 + 下次 wake 间隔推荐（PLAN-H9 §4.5 WP-05）。
+#
+# Spec letter 工程修订（disclosure）：
+#   PLAN-H9 §4.5 原文写"shell 脚本 ... 内部调用 ScheduleWakeup MCP"。落地阶段
+#   发现 ScheduleWakeup 是 CC agent loop 内部 tool API，shell 进程没有合法 RPC
+#   入口直接调用——必须由 CC agent（主窗口）调用。本脚本因此切分为：
+#     [shell 层] inbox-poll.sh = 状态检查 + 推荐间隔 → stdout 状态
+#     [agent 层] 主 agent 读 stdout 后自行决定下一次 ScheduleWakeup 时机
+#   切分边界已在 PLAN-H9 §4.5 + §11 letter 对齐时点明，记入 ADR-H9 修订建议。
+#
+# 输出：纯 KV 文本（不是 hook IO JSON），主 agent 解读后调度。
+#   unread_count=<int>
+#   p0_exists=<true|false>
+#   oldest_unread_age_seconds=<int|0>
+#   recommended_wake_seconds=<int>
+#
+# Hook IO 红线：本文件**不是** CC hook（不在 .boll/settings.json 注册），
+# 是主 agent 用 Bash tool 主动调用的检查脚本。无 print(json.dumps) / echo
+# permissionDecision / echo systemMessage 等 banned form——由 PLAN-H9 §8 显式
+# grep DoD 物理校验。
+
+set -euo pipefail
+
+# 主仓 root 检测（与 find-project-root.sh 语义对齐）
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"
+INBOX_ROOT="${REPO_ROOT}/.boll/inbox"
+MAIN_UNREAD="${INBOX_ROOT}/main/unread"
+
+# 默认间隔常量（见 ADR-H9 §6.3 ScheduleWakeup 边界）
+NORMAL_WAKE_SECONDS="${INBOX_POLL_NORMAL_WAKE:-1200}"   # 20 分钟（cache 友好）
+P0_WAKE_SECONDS="${INBOX_POLL_P0_WAKE:-300}"            # 5 分钟（CC ScheduleWakeup 最短允许下限）
+
+# unread 计数
+unread_count=0
+if [ -d "${MAIN_UNREAD}" ]; then
+  unread_count="$(find "${MAIN_UNREAD}" -maxdepth 1 -type f -name '*.md' 2>/dev/null | wc -l | tr -d ' ')"
+fi
+
+# 是否存在 priority=P0 消息
+p0_exists=false
+if [ "${unread_count}" -gt 0 ]; then
+  if grep -lE '^priority:[[:space:]]*P0[[:space:]]*$' "${MAIN_UNREAD}"/*.md 2>/dev/null | head -1 | grep -q .; then
+    p0_exists=true
+  fi
+fi
+
+# 最旧 unread 的 mtime delta（秒）
+oldest_age=0
+if [ "${unread_count}" -gt 0 ]; then
+  oldest_file="$(ls -1tr "${MAIN_UNREAD}"/*.md 2>/dev/null | head -1 || true)"
+  if [ -n "${oldest_file}" ] && [ -f "${oldest_file}" ]; then
+    if stat --version >/dev/null 2>&1; then
+      # GNU stat (Linux)
+      oldest_mtime="$(stat -c %Y "${oldest_file}" 2>/dev/null || echo 0)"
+    else
+      # BSD stat (macOS)
+      oldest_mtime="$(stat -f %m "${oldest_file}" 2>/dev/null || echo 0)"
+    fi
+    now="$(date +%s)"
+    oldest_age="$((now - oldest_mtime))"
+  fi
+fi
+
+# 推荐 wake 间隔
+if [ "${p0_exists}" = "true" ]; then
+  recommended="${P0_WAKE_SECONDS}"
+else
+  recommended="${NORMAL_WAKE_SECONDS}"
+fi
+
+# 输出（KV 纯文本，主 agent 用 grep / awk 解读）
+printf 'unread_count=%s\n' "${unread_count}"
+printf 'p0_exists=%s\n' "${p0_exists}"
+printf 'oldest_unread_age_seconds=%s\n' "${oldest_age}"
+printf 'recommended_wake_seconds=%s\n' "${recommended}"
+printf 'note=ScheduleWakeup MCP must be invoked by main agent (shell cannot reach CC internal tool API)\n'

package/src/bollharness/scripts/hooks/precompact.sh

@@ -0,0 +1,56 @@
+#!/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）："
+    npx ts-node -e "
+import * as fs from 'fs';
+const data = JSON.parse(fs.readFileSync(process.env.PROGRESS_FILE!, 'utf-8'));
+console.log('  ' + (data.objective || '<未设置>'));
+console.log();
+const pending = (data.features || []).filter((f: { status: string }) => f.status !== 'passing');
+if (pending.length) {
+    console.log('**未完成 features**：');
+    pending.forEach((f: { status: string; id: string; subject: string }) => {
+        console.log('  - [' + f.status + '] ' + f.id + ': ' + f.subject);
+    });
+} else {
+    console.log('**所有 features 已 passing**，可以进入 Stop 流程。');
+}
+" 2>&1
+fi
+
+exit 0

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

@@ -0,0 +1,83 @@
+# Stop Hook: Completion Proposal + Independent Review (ADR-044 §3.4 L3+L4)
+
+你**不是** Evaluator。你是被评估的一方。你的工作是：
+1. 写出你做了什么（proposal）
+2. 请一个独立 agent 来评你
+
+**禁止自己给自己打分。** 自评有结构性利益冲突（Anthropic: "Agents consistently overpraise their own work"）。
+
+## Step 1: 写 Completion Proposal
+
+将以下 JSON 写入 `.boll/state/completion-proposal.json`：
+
+```json
+{
+  "session_id": "<当前 session 标识>",
+  "timestamp": "<ISO 8601>",
+  "summary": "<1-3 句话描述本 session 做了什么>",
+  "files_changed": ["<从 git diff 或 risk-snapshot 获取>"],
+  "evidence": {
+    "tests_run": "<运行了哪些测试，结果如何>",
+    "verification_commands": ["<实际执行的验证命令>"],
+    "commits": ["<本 session 的 commit hash + message>"]
+  },
+  "known_limitations": ["<诚实列出已知的未完成项或风险>"],
+  "task_reference": "<TASK.md 路径或用户原始指令摘要>"
+}
+```
+
+**要求**：
+- `files_changed` 必须从 `git diff` 或 risk-snapshot 的 `files_touched` 取，**不得凭记忆列举**
+- `evidence` 中的测试结果必须是实际运行输出，不是"应该通过"
+- `known_limitations` 必须诚实 — 这是给 reviewer 的线索，不是给自己开脱
+
+## Step 2: Spawn 独立 Reviewer
+
+写完 proposal 后，**必须** spawn 一个独立审查 agent：
+
+```
+Agent({
+  subagent_type: "review-readonly",
+  description: "Completion review",
+  prompt: `你是独立的 Completion Reviewer（ADR-044 L4）。
+你的任务是验证 agent 的 completion proposal 是否与实际代码变更一致。
+
+读取 .boll/state/completion-proposal.json，然后：
+
+1. **Proposal vs Reality**：git diff 的实际变更是否与 proposal.files_changed 一致？有遗漏吗？
+2. **Evidence 可信度**：proposal.evidence 中声称的测试/验证，结果是否真实？
+3. **半成品检查**：变更文件中有没有 TODO/FIXME/HACK？有没有 dead code？
+4. **契约一致性**：如果改了 API/config/路由，所有引用处是否同步更新？
+5. **已知限制诚实度**：proposal.known_limitations 是否遗漏了明显风险？
+
+评分（每维 1-5，任何维 < 3 = FAIL）：
+- Completeness: proposal 是否覆盖所有实际变更
+- Honesty: evidence 和 limitations 是否真实
+- Quality: 代码变更本身的质量
+- Consistency: 跨文件/跨层的一致性
+
+输出格式：
+## Verdict: PASS / FAIL
+## Scores: Completeness X/5, Honesty X/5, Quality X/5, Consistency X/5
+## Findings: [具体发现列表]
+## Recommendation: [如果 FAIL，具体要修什么]`
+})
+```
+
+## Step 3: 根据 Reviewer 裁决行动
+
+- **Reviewer 说 PASS** → 你可以 Stop
+- **Reviewer 说 FAIL** → 按 Recommendation 修复，修复后再尝试 Stop
+- **Reviewer spawn 失败**（超时/权限等）→ 降级为 PreCompletionChecklist 自检（下方），但必须在输出中声明 "独立审查未执行，以下为自检降级"
+
+## 降级 Fallback: PreCompletionChecklist（仅当 reviewer 不可用时）
+
+如果因环境限制无法 spawn reviewer，执行以下自检：
+
+1. **Git 状态**: 所有新文件是否已 `git add`？是否有未保存的变更？
+2. **测试**: 如果有代码变更，相关测试是否通过？
+3. **文档一致性**: 代码变更是否需要更新文档？
+4. **无半成品**: 是否有 TODO/FIXME/HACK 被遗留？
+5. **契约一致性**: API 类型、路由路径、配置 key 是否在所有引用处一致？
+
+**但必须标注**：这是自检降级，不是独立审查。

package/src/bollharness/scripts/sync-from-upstream.sh

@@ -0,0 +1,281 @@
+#!/bin/bash
+# sync-from-upstream.sh — Sync hook files from boll (upstream) to bollharness.
+#
+# Purpose: boll is the development/incubation repo where hooks are written
+# and tested. This script copies updated hooks to bollharness and reports
+# any discrepancies in settings.json hook registrations.
+#
+# What it does:
+#   1. Copy shared hook scripts from boll → bollharness (skip boll-only files)
+#   2. Replace find-boll-root.sh references → find-project-root.sh in copied files
+#   3. Compare settings.json hook registrations and report differences
+#   4. Sync shared scripts (guard-feedback.ts, deploy-guard.ts, context_router.ts, guard_router.ts)
+#   5. Sync context-fragments/ directory
+#
+# Usage:
+#   ./scripts/sync-from-upstream.sh                     # default boll path
+#   ./scripts/sync-from-upstream.sh /path/to/boll      # explicit upstream path
+#   ./scripts/sync-from-upstream.sh --dry-run            # show what would change
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+HARNESS_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+UPSTREAM_DEFAULT="$(cd "$HARNESS_ROOT/../boll" 2>/dev/null && pwd || echo "")"
+
+# Parse args
+DRY_RUN=false
+UPSTREAM=""
+
+for arg in "$@"; do
+    case "$arg" in
+        --dry-run) DRY_RUN=true ;;
+        *) UPSTREAM="$arg" ;;
+    esac
+done
+
+if [ -z "$UPSTREAM" ]; then
+    UPSTREAM="$UPSTREAM_DEFAULT"
+fi
+
+if [ -z "$UPSTREAM" ] || [ ! -d "$UPSTREAM/scripts/hooks" ]; then
+    echo "ERROR: Cannot find upstream boll repo."
+    echo "Usage: $0 [--dry-run] [/path/to/boll]"
+    exit 1
+fi
+
+echo "=== bollharness sync-from-upstream ==="
+echo "Upstream: $UPSTREAM"
+echo "Target:   $HARNESS_ROOT"
+echo "Dry run:  $DRY_RUN"
+echo ""
+
+# ─── Files that exist only in boll (not synced) ───
+boll_ONLY=(
+    "find-boll-root.sh"  # boll-specific root finder
+)
+
+# ─── Files that exist only in bollharness (not overwritten) ───
+HARNESS_ONLY=(
+    "find-project-root.sh"  # Generic root finder
+    "sanitize-on-read.ts"   # WP-11 addition
+)
+
+# ─── Step 1: Copy shared hooks ───
+echo "── Step 1: Sync hook scripts ──"
+COPIED=0
+SKIPPED=0
+UNCHANGED=0
+
+for src_file in "$UPSTREAM/scripts/hooks/"*; do
+    [ -f "$src_file" ] || continue  # skip directories (e.g. __pycache__)
+    filename="$(basename "$src_file")"
+
+    # Skip boll-only files
+    skip=false
+    for excl in "${boll_ONLY[@]}"; do
+        if [ "$filename" = "$excl" ]; then
+            skip=true
+            break
+        fi
+    done
+    if $skip; then
+        echo "  SKIP (boll-only): $filename"
+        ((SKIPPED++))
+        continue
+    fi
+
+    # Skip harness-only files (don't overwrite)
+    for excl in "${HARNESS_ONLY[@]}"; do
+        if [ "$filename" = "$excl" ]; then
+            skip=true
+            break
+        fi
+    done
+    if $skip; then
+        echo "  SKIP (harness-only): $filename"
+        ((SKIPPED++))
+        continue
+    fi
+
+    dst_file="$HARNESS_ROOT/scripts/hooks/$filename"
+
+    # Check if content differs
+    if [ -f "$dst_file" ]; then
+        if diff -q "$src_file" "$dst_file" > /dev/null 2>&1; then
+            ((UNCHANGED++))
+            continue
+        fi
+    fi
+
+    if $DRY_RUN; then
+        echo "  WOULD COPY: $filename"
+    else
+        cp "$src_file" "$dst_file"
+        echo "  COPIED: $filename"
+    fi
+    ((COPIED++))
+done
+
+echo ""
+echo "  Results: $COPIED copied, $SKIPPED skipped, $UNCHANGED unchanged"
+
+# ─── Step 2: Replace find-boll-root.sh references ───
+echo ""
+echo "── Step 2: Path references ──"
+PATCHED=0
+
+for hook_file in "$HARNESS_ROOT/scripts/hooks/"*.ts "$HARNESS_ROOT/scripts/hooks/"*.sh; do
+    [ -f "$hook_file" ] || continue
+    filename="$(basename "$hook_file")"
+
+    # Skip harness-only files
+    skip=false
+    for excl in "${HARNESS_ONLY[@]}"; do
+        if [ "$filename" = "$excl" ]; then
+            skip=true
+            break
+        fi
+    done
+    if $skip; then continue; fi
+
+    if grep -q "find-boll-root.sh" "$hook_file" 2>/dev/null; then
+        if $DRY_RUN; then
+            echo "  WOULD PATCH: $filename (find-boll-root.sh → find-project-root.sh)"
+        else
+            # Use perl for reliable in-place replace (macOS sed -i differs from GNU)
+            perl -pi -e 's/find-boll-root\.sh/find-project-root.sh/g' "$hook_file"
+            echo "  PATCHED: $filename"
+        fi
+        ((PATCHED++))
+    fi
+done
+
+if [ "$PATCHED" -eq 0 ]; then
+    echo "  No path references to patch"
+fi
+
+# ─── Step 3: Compare settings.json hook registrations ───
+echo ""
+echo "── Step 3: Hook registration diff ──"
+
+# Extract hook script names from settings.json
+extract_hooks() {
+    npx ts-node -e "
+import json, sys
+const d = JSON.parse(require('fs').readFileSync('$1', 'utf8'));
+const hooks = [];
+for (const [stage, entries] of Object.entries(d.get('hooks', {}))) {
+    for (const entry of entries) {
+        const matcher = entry.get('matcher', '*');
+        for (const h of entry.get('hooks', [])) {
+            const cmd = h.get('command', '');
+            // Extract script name
+            const parts = cmd.split(' ');
+            for (let i = parts.length - 1; i >= 0; i--) {
+                if (parts[i].endsWith('.ts') || parts[i].endsWith('.sh')) {
+                    hooks.push(\`\${stage}|\${matcher}|\${parts[i].split('/').pop()}\`);
+                    break;
+                }
+            }
+        }
+    }
+}
+for (const h of [...new Set(hooks)].sort()) console.log(h);
+" 2>/dev/null
+}
+
+UPSTREAM_HOOKS=$(extract_hooks "$UPSTREAM/.boll/settings.json")
+HARNESS_HOOKS=$(extract_hooks "$HARNESS_ROOT/.boll/settings.json")
+
+# Find hooks only in upstream
+ONLY_UPSTREAM=$(comm -23 <(echo "$UPSTREAM_HOOKS") <(echo "$HARNESS_HOOKS"))
+ONLY_HARNESS=$(comm -13 <(echo "$UPSTREAM_HOOKS") <(echo "$HARNESS_HOOKS"))
+
+if [ -n "$ONLY_UPSTREAM" ]; then
+    echo "  ⚠ Only in boll (missing from bollharness):"
+    echo "$ONLY_UPSTREAM" | while IFS='|' read -r stage matcher script; do
+        echo "    $stage $matcher: $script"
+    done
+fi
+
+if [ -n "$ONLY_HARNESS" ]; then
+    echo "  ℹ Only in bollharness (expected for harness-specific hooks):"
+    echo "$ONLY_HARNESS" | while IFS='|' read -r stage matcher script; do
+        echo "    $stage $matcher: $script"
+    done
+fi
+
+if [ -z "$ONLY_UPSTREAM" ] && [ -z "$ONLY_HARNESS" ]; then
+    echo "  ✓ Hook registrations in sync"
+fi
+
+# ─── Step 4: Check for other synced files ───
+echo ""
+echo "── Step 4: Other shared files ──"
+
+# Scripts in scripts/ root that are shared with boll
+for shared_file in "guard-feedback.ts" "deploy-guard.ts" "context_router.ts" "guard_router.ts"; do
+    src="$UPSTREAM/scripts/$shared_file"
+    dst="$HARNESS_ROOT/scripts/$shared_file"
+    if [ -f "$src" ] && [ -f "$dst" ]; then
+        if ! diff -q "$src" "$dst" > /dev/null 2>&1; then
+            if $DRY_RUN; then
+                echo "  WOULD COPY: scripts/$shared_file"
+            else
+                cp "$src" "$dst"
+                echo "  COPIED: scripts/$shared_file"
+            fi
+        fi
+    elif [ -f "$src" ] && [ ! -f "$dst" ]; then
+        echo "  ⚠ MISSING in harness: scripts/$shared_file"
+    fi
+done
+
+# ─── Step 5: Sync context-fragments/ directory ───
+echo ""
+echo "── Step 5: Context fragments ──"
+FRAG_COPIED=0
+FRAG_UNCHANGED=0
+
+src_frag_dir="$UPSTREAM/scripts/context-fragments"
+dst_frag_dir="$HARNESS_ROOT/scripts/context-fragments"
+
+if [ -d "$src_frag_dir" ]; then
+    if [ ! -d "$dst_frag_dir" ]; then
+        if $DRY_RUN; then
+            echo "  WOULD CREATE: scripts/context-fragments/"
+        else
+            mkdir -p "$dst_frag_dir"
+            echo "  CREATED: scripts/context-fragments/"
+        fi
+    fi
+
+    for src_frag in "$src_frag_dir/"*; do
+        [ -f "$src_frag" ] || continue
+        frag_name="$(basename "$src_frag")"
+        dst_frag="$dst_frag_dir/$frag_name"
+
+        if [ -f "$dst_frag" ]; then
+            if diff -q "$src_frag" "$dst_frag" > /dev/null 2>&1; then
+                ((FRAG_UNCHANGED++))
+                continue
+            fi
+        fi
+
+        if $DRY_RUN; then
+            echo "  WOULD COPY: context-fragments/$frag_name"
+        else
+            cp "$src_frag" "$dst_frag"
+            echo "  COPIED: context-fragments/$frag_name"
+        fi
+        ((FRAG_COPIED++))
+    done
+
+    echo "  Results: $FRAG_COPIED copied, $FRAG_UNCHANGED unchanged"
+else
+    echo "  ⚠ Upstream context-fragments/ not found"
+fi
+
+echo ""
+echo "=== Sync complete ==="

package/src/bollharness/src/index.ts

@@ -0,0 +1,5 @@
+export { Finding, createFinding } from "./scripts/checks/finding";
+export { route, runGuards, writeSessionSignal, readAllSignals, GUARD_MAP, DEFAULT_GUARDS, CATEGORY_TO_SKILLS } from "./scripts/guard_router";
+export { match, loadFragment, FALLBACK_FRAGMENTS, CONTEXT_MAP } from "./scripts/context_router";
+export { main as guardFeedbackMain } from "./scripts/guard-feedback";
+export { main as deployGuardMain } from "./scripts/deploy-guard";

package/src/bollharness/src/scripts/checks/check_adr_plan_numbering.ts

@@ -0,0 +1,11 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Finding } from "./finding";
+
+export function run(repoRoot: string, mode: string = "full"): Finding[] {
+  const findings: Finding[] = [];
+
+  if (mode !== "full" && mode !== "ci") return findings;
+
+  return findings;
+}

package/src/bollharness/src/scripts/checks/check_api_types.ts

@@ -0,0 +1,52 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Finding } from "./finding";
+
+export function run(repoRoot: string, mode: string = "full"): Finding[] {
+  const findings: Finding[] = [];
+
+  const tsFile = path.join(repoRoot, "generated", "api-types.ts");
+  if (!fs.existsSync(tsFile)) {
+    findings.push({
+      severity: "P1",
+      message: "generated/api-types.ts does not exist — run scripts/export_api_types.py",
+      file: "generated/api-types.ts",
+      blocking: false,
+      category: "general",
+      problem_class: "unknown",
+      required_skills: [],
+      required_reads: [],
+    });
+    return findings;
+  }
+
+  const content = fs.readFileSync(tsFile, "utf-8");
+  const interfaceMatch = content.match(/export interface (\w+) \{/g);
+
+  if (!interfaceMatch) {
+    findings.push({
+      severity: "P1",
+      message: "generated/api-types.ts contains no interfaces",
+      file: "generated/api-types.ts",
+      blocking: false,
+      category: "general",
+      problem_class: "unknown",
+      required_skills: [],
+      required_reads: [],
+    });
+    return findings;
+  }
+
+  findings.push({
+    severity: "P2",
+    message: "API type checking requires backend model comparison (Python 3.10+ backend not available in TypeScript check)",
+    file: "generated/api-types.ts",
+    blocking: false,
+    category: "general",
+    problem_class: "unknown",
+    required_skills: [],
+    required_reads: [],
+  });
+
+  return findings;
+}