@bolloon/bolloon-agent 0.1.0

package/src/bollharness/.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: bollharness CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  safety-scans:
+    name: safety-scans
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout (full history for claim git-log checks)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install deps
+        run: npm install
+
+      # ------------------------------------------------------------------
+      # Core sanitize + L1/L2 integrity
+      # ------------------------------------------------------------------
+      - name: count-components + meta-self-check
+        # AC 2/3: meta-self-check fires if ci.yml no longer references
+        # count-components.sh. This line IS the anchor — don't rename it.
+        run: bash scripts/ci/count-components.sh
+
+      - name: scan yaml schema (ban cmd_template/exec in settings.json + yaml)
+        run: |
+          npx ts-node scripts/ci/scan_yaml_schema.ts .boll/settings.json
+          npx ts-node scripts/ci/scan_yaml_schema.ts .boll/MANIFEST.yaml
+          npx ts-node scripts/ci/scan_yaml_schema.ts .boll/issue-adapter.yaml
+          npx ts-node scripts/ci/scan_yaml_schema.ts .boll/deploy-allowlist.yaml
+
+      - name: scan subprocess cfg (ts hooks + root scripts)
+        run: |
+          find scripts -name '*.ts' -not -path 'scripts/fragments/*' -print0 \
+            | xargs -0 -r npx ts-node scripts/ci/scan_subprocess_cfg.ts
+
+      - name: scan verify artifacts — positive claim cross-source
+        run: npx ts-node scripts/ci/scan_verify_artifacts.ts --claims
+
+      - name: detect rebaseline triggers (MANIFEST vs live)
+        run: npx ts-node scripts/ci/detect_rebaseline_triggers.ts
+
+      # ------------------------------------------------------------------
+      # WP-SEC-1 seam verifiers
+      # ------------------------------------------------------------------
+      - name: lead INDEX install-bollharness slot preserved (patch_d)
+        run: grep -q 'install-bollharness' .boll/skills/lead/INDEX.md
+
+      - name: settings.json command count (15 pre-WP-11, 16 post-WP-11)
+        run: |
+          N=$(npx ts-node -e "import fs from 'fs'; const s=JSON.parse(fs.readFileSync('.boll/settings.json','utf8')); console.log(Object.values(s.hooks||{}).flat().reduce((a,e)=>a+(e.hooks||[]).length,0))")
+          echo "settings.json command count: $N"
+          case "$N" in
+            15|16) echo "ok";;
+            *) echo "UNEXPECTED command count: $N (expected 15 pre-WP-11 or 16 post-WP-11)"; exit 2;;
+          esac
+
+      - name: MANIFEST L-registry schema (8 required top-level keys)
+        run: |
+          npx ts-node - <<'TS'
+          import fs from 'fs';
+          const yaml = require('js-yaml');
+          const d = yaml.load(fs.readFileSync('.boll/MANIFEST.yaml', 'utf8'));
+          const required = [
+              'L1_registry', 'L2_registry', 'L3_registry', 'L4_registry',
+              'L5_registry', 'settings_command_registry', 'rebaseline_triggers',
+              'physical_files',
+          ];
+          const missing = required.filter(k => !(k in d));
+          if (missing.length > 0) {
+              console.log('missing MANIFEST keys:', missing);
+              process.exit(2);
+          }
+          assert(d['L1_registry'].length > 0, 'L1_registry must be non-empty');
+          assert([15, 16].includes(d['settings_command_registry'].length),
+              `settings_command_registry length ${d['settings_command_registry'].length} not in (15, 16)`);
+          console.log('MANIFEST schema ok');
+          TS

package/src/bollharness/.sanitize-report.json

@@ -0,0 +1,13 @@
+{
+  "schema_version": "1.0",
+  "last_scan": "2026-04-19T00:00:00+08:00",
+  "total_files_scanned": 0,
+  "findings": [],
+  "statistics": {
+    "secrets": 0,
+    "trade_secrets": 0,
+    "pii": 0,
+    "network_internal": 0,
+    "protocol_internal": 0
+  }
+}

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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bollharness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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