@bolloon/bolloon-agent 0.1.0

package/src/bollharness/.claude/agents/review-base.yaml

@@ -0,0 +1,108 @@
+# Review Agent Tool Isolation — 共享白名单规范
+# [来源: ADR-038 D11.1 + OpenDev arXiv 2603.05344 — Plan mode planner schema-level read-only exclusion]
+#
+# 这个文件不是 agent definition，而是**机器可读的白名单规范**。
+# 所有审查类 agent 的 frontmatter 必须遵循这个白名单。
+# 治理规则在 .boll/rules/review-agent-isolation.md。
+#
+# 关键原则：
+# 1. 审查 agent 的工作是"看 + 报告"，不是"改"
+# 2. schema-level 隔离比 prompt-level 约束可靠 100x（OpenDev 论文证据）
+# 3. 不允许 Edit/Write/Bash/NotebookEdit — 这些有潜在副作用
+# 4. WebFetch + Read + Grep + Glob 足够支持任何审查工作
+#
+# 适用范围（非穷尽）：
+# - 任何 PR review / code review 类 agent
+# - Stop hook 的 Evaluator subagent
+# - Gate 2/4/6/8 审查 subagent
+# - Silent failure / type design / security review 类 agent
+# - Architectural consistency 检查 agent
+
+version: 1.0.0
+last_updated: "2026-04-07"
+spec_source: "ADR-038 D11"
+
+# ──────────────────────────────────────────────────────────────────────────
+# 允许的工具（白名单 — 完整列表）
+# ──────────────────────────────────────────────────────────────────────────
+tools_allowed:
+  # 信息读取
+  - Read              # 读文件
+  - Glob              # 文件路径模式匹配
+  - Grep              # 内容搜索（内置 ripgrep）
+
+  # 外部资源（只读）
+  - WebFetch          # 查文档、ADR 引用、外部规范
+  - WebSearch         # 搜索（不修改任何东西）
+
+  # 自我管理（不影响 host 系统）
+  - TodoWrite         # 自己的检查清单
+  - TaskCreate        # 创建跟进 task
+  - TaskUpdate        # 更新自己 task 状态
+  - TaskList          # 查看 task 列表
+  - TaskGet           # 读 task 详情
+
+  # MCP 只读工具（按需选择）
+  - mcp__boll__boll_*  # boll 协议查询（agents/demands/runs 等只读 tool）
+
+# ──────────────────────────────────────────────────────────────────────────
+# 禁用的工具（黑名单 — 必须显式拒绝）
+# ──────────────────────────────────────────────────────────────────────────
+tools_denied:
+  # 写入类 — 一律拒绝
+  - Edit              # 改文件
+  - Write             # 写新文件
+  - NotebookEdit      # 改 Jupyter notebook
+
+  # Shell 类 — 一律拒绝（即使"只读"命令也可能有副作用）
+  - Bash              # 包括 git push, rm, scp, npm install 等
+
+  # Worktree / 长任务类 — 审查不应改 git 状态
+  - EnterWorktree
+  - ExitWorktree
+
+  # 远程触发类 — 审查不应启动 cron
+  - CronCreate
+  - CronDelete
+
+  # 写权限的 MCP 工具（按 MCP server 列出）
+  - mcp__boll__boll_register
+  - mcp__boll__boll_login
+  - mcp__boll__boll_logout
+  - mcp__boll__boll_*_create
+  - mcp__boll__boll_*_delete
+  - mcp__boll__boll_*_update
+  - mcp__boll__boll_send_message
+  - mcp__boll__boll_*_respond
+  - mcp__boll__boll_*_confirm
+
+# ──────────────────────────────────────────────────────────────────────────
+# 候选 Bash 只读子集（v4 仅文档化，未实施 — 需要 PreToolUse hook 强制）
+# ──────────────────────────────────────────────────────────────────────────
+# 设计上 review agent 不应该用 Bash，但如果必须，只允许这些模式：
+bash_allowed_patterns:
+  - "git status"
+  - "git diff*"
+  - "git log*"
+  - "git show*"
+  - "git blame*"
+  - "ls *"            # 应该用 Glob 替代
+
+# ──────────────────────────────────────────────────────────────────────────
+# 应用清单：哪些 agent 必须遵循
+# ──────────────────────────────────────────────────────────────────────────
+# 本地 / 插件 review agents（直接由 frontmatter 控制）：
+#   - .boll/plugins/boll-review-toolkit/agents/reviewer.md (WP-040 backport；reference implementation)
+#
+# 插件 review agents（无法改 frontmatter，需要在调用层用约束 prompt 引用本规范）：
+#   - pr-review-toolkit:code-reviewer
+#   - pr-review-toolkit:silent-failure-hunter
+#   - pr-review-toolkit:type-design-analyzer
+#   - pr-review-toolkit:comment-analyzer
+#   - pr-review-toolkit:pr-test-analyzer
+#   - feature-dev:code-explorer
+#   - feature-dev:code-reviewer
+#
+# Stop hook Evaluator (scripts/hooks/stop-evaluator.md)：
+#   - 不是 subagent，而是 hook 注入的 prompt
+#   - 该 prompt 不能调用任何工具（只输出文字反馈）

package/src/bollharness/.claude/plugins/boll-mode-toolkit/.claude-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "boll-mode-toolkit",
+  "version": "0.1.0",
+  "description": "Runtime mode + capability-routing + evidence-emit substrate for boll runs. Ships the PreToolUse capability-router (mode-enforced tool allowlist/denylist + shadow logging), the PostToolUse evidence-emit hook (auto-captures step-level evidence packets), the /mode skill family (plan/build/verify/release transitions gated against .boll/state/mode + review-contract bindings), and the mode-contract.md runtime-state-variable specification. Sibling to boll-review-toolkit (WP-037). Second asset-unit export per 03-design.md §11.1 — the mode-first control plane becomes importable.",
+  "author": {
+    "name": "boll",
+    "url": "https://github.com/natureblueee/boll"
+  },
+  "license": "MIT",
+  "keywords": [
+    "boll",
+    "mode",
+    "capability-router",
+    "evidence-emit",
+    "pretooluse",
+    "posttooluse"
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SHADOW=1 npx ts-node \"${CLAUDE_PLUGIN_ROOT}/hooks/capability-router.ts\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ts-node \"${CLAUDE_PLUGIN_ROOT}/hooks/evidence-emit.ts\" 2>/dev/null || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/bollharness/.claude/plugins/boll-review-toolkit/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "boll-review-toolkit",
+  "version": "0.1.0",
+  "description": "Review substrate for boll runs: contract-driven Stop gate (verify-gate) + read-only reviewer subagent + evidence-packet schema + review-contract bindings. Ships the four assets that together implement Phase 1 §3.3 (Stop ≠ Completion ≠ Transition) and Phase 2 §3.8 (closure = commit + packet). Activating the plugin wires verify-gate as the project's Stop hook; the reviewer subagent spawns via merge-ready-review binding.",
+  "author": {
+    "name": "boll",
+    "url": "https://github.com/natureblueee/boll"
+  },
+  "license": "MIT",
+  "keywords": ["boll", "review", "evidence-packet", "stop-gate", "subagent"],
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx ts-node \"${CLAUDE_PLUGIN_ROOT}/hooks/verify-gate.ts\" 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/bollharness/.claude/plugins/boll-review-toolkit/contracts/evidence-packet-schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://bollharness.local/schemas/evidence-packet-v1.json",
+  "title": "boll vNext Evidence Packet",
+  "description": "Canonical shape of a completion / verification evidence packet. Every evidence file under .boll/evidence/<run-id>/ MUST validate against this schema. Referenced by ../hooks/verify-gate.ts. Addresses Phase 1 §2.7 / §3.1 / open-question A.7 (no explicit completion-evidence artifact existed). Grounded in Phase 2 §4.4 (PRM) and §3.8 (closure = commit + packet).",
+  "type": "object",
+  "required": ["packet_id", "run_id", "step_id", "mode", "kind", "created_at", "author", "claims", "evidence", "digest"],
+  "additionalProperties": false,
+  "properties": {
+    "packet_id": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "sha256 of the canonical-JSON serialization of this packet with digest omitted."
+    },
+    "run_id": {
+      "type": "string",
+      "pattern": "^[0-9a-zA-Z_-]{8,64}$"
+    },
+    "step_id": {
+      "type": "string",
+      "description": "Stable per-step identifier: step number or sub-task id. For run-level packets (MERGE_READY), use 'FINAL'."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["plan", "build", "verify", "release"]
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["step", "gate", "merge_ready", "retire"],
+      "description": "step = per-edit evidence; gate = mode-transition gate; merge_ready = run-level completion; retire = asset retirement packet."
+    },
+    "created_at": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "author": {
+      "type": "object",
+      "required": ["kind", "id"],
+      "properties": {
+        "kind": {"enum": ["model", "hook", "human"]},
+        "id": {"type": "string", "description": "model name, hook script path, or human user id"}
+      }
+    },
+    "claims": {
+      "type": "array",
+      "minItems": 1,
+      "description": "What the author says was accomplished. Plain strings.",
+      "items": {"type": "string", "minLength": 4, "maxLength": 240}
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Concrete substantiation per claim. Every claim must have ≥1 matching evidence entry.",
+      "items": {
+        "type": "object",
+        "required": ["claim_index", "type", "ref"],
+        "additionalProperties": false,
+        "properties": {
+          "claim_index": {"type": "integer", "minimum": 0},
+          "type": {
+            "type": "string",
+            "enum": ["commit_sha", "test_result", "file_hash", "command_output", "external_link", "human_attestation"]
+          },
+          "ref": {"type": "string", "description": "commit sha / test name / file path / url / attestation id"},
+          "summary": {"type": "string", "maxLength": 240},
+          "pass": {"type": "boolean", "description": "only for test_result / command_output"}
+        }
+      }
+    },
+    "blockers": {
+      "type": "array",
+      "description": "Known issues that should block closure at the current mode. Empty = no blockers declared.",
+      "items": {
+        "type": "object",
+        "required": ["severity", "note"],
+        "properties": {
+          "severity": {"enum": ["info", "warn", "block"]},
+          "note": {"type": "string", "minLength": 4, "maxLength": 480},
+          "owner": {"type": "string"}
+        }
+      }
+    },
+    "unknowns": {
+      "type": "array",
+      "description": "Explicit UNKNOWNs the author cannot resolve. Surfacing them here is required — silent omission is a verify-gate fail (Phase 1 §6.1 affordance failure).",
+      "items": {"type": "string", "minLength": 4, "maxLength": 480}
+    },
+    "predecessors": {
+      "type": "array",
+      "description": "packet_ids this packet builds on (forms the run's evidence DAG).",
+      "items": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
+    },
+    "digest": {
+      "type": "object",
+      "required": ["algorithm", "value"],
+      "properties": {
+        "algorithm": {"const": "sha256"},
+        "value": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
+      }
+    }
+  }
+}

package/src/bollharness/.claude/plugins/boll-review-toolkit/contracts/review-contract.yaml

@@ -0,0 +1,247 @@
+# boll vNext Review Contract
+# Companion to ../03-design.md §8. Addresses Phase 1 §6.2 (capability-delivery contradiction),
+# §3.3 (review-agent-gatekeeper matcher-miss), §3.1 (review-agent-isolation.md).
+# Grounded in Phase 2 §3.8 (closure = commit + packet), §2.1 (Codex review-pane pattern).
+#
+# A review-contract binding declares WHAT a review does. Each review mode is one of:
+#   pane      — reviewer is a diff pane + evidence packet produced by a tool (no agent spawn)
+#   subagent  — reviewer is a read-only subagent with strict tool whitelist
+#   human     — human is the reviewer; harness packages the evidence
+#
+# The single source of truth. No review happens outside a binding that parses as this schema.
+#
+# Evidence packet schema reference: `./evidence-packet-schema.json` (plugin-relative;
+#   co-located in this plugin's contracts/ directory per WP-037 packaging).
+#   Every `outputs.evidence_packet` below must conform to that schema; verify-gate.ts
+#   (WP-024) validates producer- and consumer-side agreement.
+#
+# Per-binding `active` field: true = binding is live; false = binding is present
+# but inert (parses, references the schema, but triggers no gate yet). WP-022
+# activates only `design-review` and `retirement-review` (the two human-gated
+# bindings); `default-build-review` and `merge-ready-review` ship as inactive
+# placeholders, activated later by WP-026 and WP-027 respectively.
+
+schema_version: 1
+evidence_packet_schema_ref: ./evidence-packet-schema.json
+
+# ── ADR-H5 §3 INV-H5-1: line_caps schema 化 ──
+# 把散落在 ADR-H0/H1/H3/H4 共 4 处的行数硬限收口为顶层字段。各 cap 数值由
+# source_adr 决定（H5 仅做收口聚合 + ref 指针，不重新定义数值）。
+# 红线（INV-H5-1）：增加新 cap 项必须在原始 ADR 中先有"≤N 行"明文规定。
+line_caps:
+  - id: adr-h-series
+    glob: "docs/decisions/ADR-H*.md"
+    max_lines: 300
+    source_adr: "ADR-H0 §H0.2"
+  - id: plan-h-series
+    glob: "docs/decisions/PLAN-H*.md"
+    max_lines: 500
+    source_adr: "ADR-H0 §H0.2"
+  - id: lead-skill-h-segment
+    glob: ".boll/skills/lead/SKILL.md"
+    max_lines: 220
+    source_adr: "ADR-H1 受管资产 + ADR-H4 INV-H4-1"
+  - id: memory-master-index
+    glob: "~/.boll/projects/-Users-nature------boll/memory/MEMORY.md"
+    max_lines: 200
+    source_adr: "ADR-H3 INV-H3-2 v1.1"
+
+# ── ADR-H5 §5 inflation 规则（3 条）──
+# 把 ADR-H0 §H0.2 行数限额 + H0.3 执检分离 + H0.4 自指禁止
+# 升级到 schema-level 字段（CC 直接读，不再 prompt-level 70%）。
+inflation:
+  no_grow_now_clean_later: true            # 规则 1: 不接受"merge 后下个 PR 拆"理由
+  drafter_reviewer_must_differ_session: true  # 规则 2: 起草人 ≠ reviewer 同 session
+  h0_self_check_segment_required: true     # 规则 3: 任何 ADR-Hx 必含 §H0 自检段
+
+# ── ADR-H6 §3 INV-H6-1: state 清单 schema 化 ──
+# 把 .boll/state + .boll/proposals + .boll/guard + .boll/log + .boll/inbox + .boll/evidence
+# 等 state 资产收口为顶层清单。kind: dynamic / archived / append-only / managed-by-other-h
+# 红线（INV-H6-1）：新增 state 资产路径必须先在原始 ADR 中宣告归属 owner。
+state_inventory:
+  - id: state-mode
+    path: ".boll/state/mode"
+    kind: dynamic
+    owner: boll-mode-toolkit
+  - id: state-run
+    path: ".boll/state/run.json"
+    kind: dynamic
+    owner: boll-mode-toolkit
+  - id: state-locks
+    path: ".boll/state/locks.json"
+    kind: dynamic
+    owner: boll-mode-toolkit
+  - id: state-completion-proposal
+    path: ".boll/state/completion-proposal.json"
+    kind: dynamic
+    owner: boll-review-toolkit
+  - id: state-risk-snapshot
+    path: ".boll/state/risk-snapshot.json"
+    kind: dynamic
+    owner: risk-tracker
+  - id: state-round-verdicts
+    path: ".boll/state/round{1-5}-verdicts/"
+    kind: archived
+    owner: harness-review-history
+  - id: state-archived-dir
+    path: ".boll/state/_archived/"
+    kind: archived
+    owner: ADR-H6
+  - id: proposals-self-evolution
+    path: ".boll/proposals/"
+    kind: append-only
+    owner: vNext-self-evolution
+    note: "265 文件; 只增不删"
+  - id: guard-loop-counter
+    path: ".boll/guard/"
+    kind: append-only
+    owner: harness-guard
+    note: "11321 文件; 活工具态非污染（H 系列调研 #4 认知修正）"
+  - id: log-self-symptoms
+    path: ".boll/log/harness-self-symptoms.md"
+    kind: append-only
+    owner: H 系列
+  - id: log-hook-ledger
+    path: ".boll/log/hook/"
+    kind: append-only
+    owner: 各 hook
+  - id: inbox-mailbox
+    path: ".boll/inbox/"
+    kind: managed-by-other-h
+    owner: ADR-H9
+    note: "main/quarantine/schema/window-h{0-6,8,9}"
+  - id: evidence-packets
+    path: ".boll/evidence/"
+    kind: managed-by-other-h
+    owner: 各 PLAN
+
+# ── ADR-H6 §3 INV-H6-2: state 健康度指标 schema 化 ──
+# 红线（INV-H6-2）：每条指标必须给出可执行 check 命令；不接受"靠人脑感知"。
+state_health_indicators:
+  - id: schema-validity
+    desc: "dynamic JSON 文件 JSON parse 通过 + 必填字段非空"
+    check: "npx ts-node -e 'import fs from \"fs\"; [\"state/run.json\",\"state/locks.json\",\"state/completion-proposal.json\",\"state/risk-snapshot.json\"].forEach(f=>JSON.parse(fs.readFileSync(f,\"utf8\")))'"
+  - id: top-level-no-noise
+    desc: ".boll/state/ 顶层无 .DS_Store / 未归档 archived 文件 / 临时文件"
+    check: "ls .boll/state/.DS_Store .boll/state/*archived*.json 2>/dev/null | wc -l"
+    expect: 0
+  - id: inbox-unread-volume
+    desc: ".boll/inbox/main/unread/ ≤50 文件（H9 ADR 红线复用）"
+    check: "ls .boll/inbox/main/unread/ 2>/dev/null | wc -l"
+    expect_max: 50
+
+bindings:
+
+  - id: default-build-review
+    active: true                           # WP-026 activation — default build closures require pane packet
+    applies_when:
+      mode: build
+      task_kind: code_change
+    reviewer:
+      type: pane
+      produces: evidence-packet:kind=gate
+    inputs:
+      - diff: git_diff_against_main
+      - tests: required_tests_for_changed_files
+      - packet: previous_step_evidence
+    outputs:
+      - evidence_packet:
+          mode: build
+          kind: gate
+          claims:
+            - "diff is small enough to review (< 400 lines changed or ≥ 1 reviewer attestation)"
+            - "all changed files have at least one test that exercises the change OR a blocker entry"
+      - blockers_surface: top_level
+    gating:
+      blocks_mode_transition_to: verify
+      bypass_requires: human_attestation
+
+  - id: merge-ready-review
+    active: true                           # WP-027 activation — merge-ready gating + reviewer subagent installed
+    applies_when:
+      mode: verify
+      transition_target: release
+    reviewer:
+      type: subagent
+      subagent_ref: reviewer            # see ../prompts/agent-reviewer.md
+      tools_whitelist:                   # CC frontmatter `tools:` list; enforced at capability layer
+        - Read
+        - Glob
+        - Grep
+        - Bash(git log:*)
+        - Bash(git diff:*)
+        - Bash(npx ts-node --collect-only:*)
+      forbidden_tools: [Edit, Write, Bash(rm:*), Bash(git push:*), SendMessage]
+      # Phase 1 open-question C.2: if delivery requires SendMessage, the runtime
+      # MUST re-spawn via a separate delivery tool; reviewer itself stays pure.
+    # ── ADR-H5 §3 INV-H5-2: 执检分离 binding 化 ──
+    # 把 ADR-H0 §H0.3 从 ad-hoc prompt 升级到 schema 字段。reviewer subagent 必须
+    # 来自白名单；verdict 文件路径必须匹配 evidence_path_pattern。
+    drafter_reviewer_separation:
+      required: true
+      rationale: "ADR-H0 §H0.3 执检分离 + ADR-038 D11.2"
+      evidence_path_pattern: "docs/decisions/tasks/PLAN-{plan}/WP-05/reviewer-verdict-*.md"
+      reviewer_subagent_whitelist:
+        - "pr-review-toolkit:code-reviewer"
+        - "boll-review-toolkit:reviewer"
+    inputs:
+      - all_step_packets: true
+      - all_gate_packets: true
+      - aggregate_diff: true
+    outputs:
+      - evidence_packet:
+          mode: verify
+          kind: merge_ready
+          must_include_unknowns: true   # Phase 1 §6.1 anti-affordance: hiding unknowns fails gate
+    gating:
+      blocks_mode_transition_to: release
+      requires_all:
+        - every_unknown_in_earlier_packets_resolved_or_explicitly_deferred
+        - no_blocker_of_severity_block
+        - aggregate_diff_ci_green
+      bypass_requires: human_attestation_with_reason_string
+
+  - id: design-review
+    active: true                           # WP-022 activation — human-gated, low-traffic
+    applies_when:
+      mode: plan
+      transition_target: build
+    reviewer:
+      type: human
+    inputs:
+      - plan_file_ref: true
+      - reasoning_trace: optional
+    outputs:
+      - evidence_packet:
+          mode: plan
+          kind: gate
+    gating:
+      blocks_mode_transition_to: build
+      bypass_requires: never            # plan → build is always human-gated
+
+  - id: retirement-review
+    active: true                           # WP-022 activation — human-gated, rare, high-blast-radius
+    applies_when:
+      operation: retire_asset
+    reviewer:
+      type: pane
+      produces: evidence-packet:kind=retire
+    inputs:
+      - asset_path: required
+      - usage_stats: last_90_days
+      - replaced_by: required_or_explicit_null
+    outputs:
+      - evidence_packet:
+          mode: release
+          kind: retire
+          claims:
+            - "asset was used fewer than N times in last 90 days OR replaced_by is non-null"
+            - "retire target is .boll/retired/<date>/ (not deleted)"
+    gating:
+      requires: human_attestation
+
+# Explicit non-bindings — work that is NOT a review:
+non_reviews:
+  - user_asks_claude_a_question        # Phase 1 §6.3 mode collapse — chat ≠ review
+  - brainstorm                          # plan mode does not auto-trigger review
+  - read_only_exploration               # no review until a change is proposed