@bolloon/bolloon-agent 0.1.0

package/src/bollharness/.claude/skills/lead/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: lead
+description: 开发流程统领 Skill。
+status: active
+tier: entry
+owner: {{PROJECT_OWNER}}
+last_audited: 2026-04-09
+---
+
+# lead
+
+开发流程统领。
+
+## 文件索引
+
+- SKILL.md — 主文件
+- INDEX.md — 本索引
+- ref-review-sop.md — 审查 SOP
+- ref-stages.md — 五阶段定义
+- install-wow-harness.md — 安装指引
+
+## 状态
+
+active

package/src/bollharness/.claude/skills/lead/install-wow-harness.md

@@ -0,0 +1,77 @@
+# /lead install bollharness
+
+## 一句话
+
+在用户的项目里安装 bollharness 开发护栏。一条命令，三种深度，开箱即用。
+
+## 使用方式
+
+```bash
+# 最常见：当前项目，默认 adapt 档
+npx ts-node scripts/install/phase2_auto.ts --auto
+
+# 指定档位
+npx ts-node scripts/install/phase2_auto.ts --auto --tier=drop-in
+npx ts-node scripts/install/phase2_auto.ts --auto --tier=adapt
+npx ts-node scripts/install/phase2_auto.ts --auto --tier=mine --projects=/path/a,/path/b
+
+# 多项目
+npx ts-node scripts/install/phase2_auto.ts --auto --projects=/path/a,/path/b --scope=explicit
+
+# 验证幂等性
+npx ts-node scripts/install/phase2_auto.ts --auto --dry-run
+```
+
+## 三档安装光谱（ADR-043 §3.4.4）
+
+| 档位 | 适合谁 | 读什么 | 做什么 |
+|------|--------|--------|--------|
+| **drop-in** | "我只要护栏，别碰我代码" | 只读 bundle 自身 | 复制 L0-L5 组件 + 16 条 hook matcher |
+| **adapt** ⭐ 默认 | "看懂我项目就行" | README.md + docs/**/*.md (50KB) | drop-in + 按 stack 启/禁 rules |
+| **mine** | "完全长进来" | adapt + 点名项目的 transcripts | adapt + crystal-learn 种子提案 |
+
+**adapt 是默认档。** 绝大多数用户不需要碰这个参数。
+
+## 显式点名（ADR-043 §3.4.5）
+
+安装器会问你装到哪里：
+
+1. 当前目录
+2. 用户级全局（~/.boll/ plugin）
+3. 显式点名几个项目
+
+**mine + 全局 = 禁止**（隐私灾难，fail-closed）。mine 档必须显式点名。
+
+## Gate 8 反思 loop（ADR-043 §3.4.6）
+
+adapt 和 mine 档安装后，当你完成一个大 plan（lead state machine Gate 8 PASS），harness 会自动在后台启动一个 crystal-learn reflection agent。
+
+这不是你需要记得做的事——它绑在 Gate 8 事件上，plan 完成就反思，不完成就不反思。
+
+反思产物在 `.boll/proposals/` 目录，下次开 session 时自然能看到。
+
+## 安全模型
+
+- **HMAC trust token**：安装过程用 `BOLLHARNESS_INSTALL_HMAC_KEY` 环境变量签名，30min 滑动窗口 + 6h 绝对上限
+- **fail-closed**：key 缺失 / 过短 / 过期 = 自动中止，不降级
+- **settings.json 原子追加**：用 json 库，不用 sed（INV-4 防护）
+- **幂等**：第二次运行检测到已安装 → 跳过，不重复写
+
+## 安装后验证
+
+```bash
+# 确认 hook 数量
+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))"
+# 预期输出: 16
+
+# 确认 sanitize-on-read 工作
+echo '{\"tool_name\":\"Read\",\"tool_input\":{\"file_path\":\"test.txt\"}}' | npx ts-node scripts/hooks/sanitize-on-read.ts
+# 预期: {"decision": "approve"}
+```
+
+## 这个 skill 不做什么
+
+- 不碰 lead 的 8-gate 状态机核心逻辑
+- 不自动扫描 ~/.boll/projects/ 推断项目（发现 = 未授权）
+- 不装 OS-level daemon（没有 launchd/systemd/cron）
+- 不在 drop-in 档读任何用户文件

package/src/bollharness/.claude/skills/lead/ref-review-sop.md

@@ -0,0 +1,48 @@
+# lead SKILL.md
+
+## 审查闭环 SOP
+
+### TeamCreate 使用规范
+
+**什么时候用 TeamCreate**：
+- Gate 2 架构审查
+- Gate 4 PLAN 审查 + plan-lock
+- Gate 6 task 审查
+- Gate 8 最终审查
+
+**什么时候用 Agent tool**：
+- 禁止用 Agent tool 做审查
+- Agent tool 是共享上下文，判断不独立
+
+### 三视角矩阵
+
+| 视角 | 关注点 |
+|------|--------|
+| 商业可行性 | 价值、风险、成本 |
+| 技术本质 | 可行性、复杂性、依赖 |
+| 用户体验 | 可用性、接受度 |
+
+### 裁决格式
+
+```
+## Verdict: PASS / FAIL
+
+## Scores
+- Completeness: X/5
+- Honesty: X/5
+- Quality: X/5
+- Consistency: X/5
+
+## Findings
+1. [具体发现]
+2. [具体发现]
+
+## Recommendation
+[如果 FAIL，具体要修什么]
+```
+
+### 生产问题诊断硬规则
+
+1. **先看日志/事件/DB**，不先看代码猜测
+2. **先隔离问题范围**，不直接全局搜索
+3. **先验证假设**，不基于假设行动

package/src/bollharness/.claude/skills/lead/ref-stages.md

@@ -0,0 +1,58 @@
+# lead SKILL.md
+
+## 五阶段定义
+
+### 阶段①：问题锁定
+
+Gate 0 的入口条件：用户提出需求。
+
+产出：问题陈述 + Change Classification。
+
+Change Classification 决定最低门禁：
+- policy：边界、身份、权限、场景承诺
+- contract：API、schema、事件、配置
+- implementation：单模块内部
+
+### 阶段②：架构设计
+
+Gate 1 的入口条件：Gate 0 产物存在。
+
+产出：ADR 草稿 + 消费方清单。
+
+消费方发现三维度：
+- 数据消费方：谁读这个数据
+- 行为消费方：谁调用这个接口
+- 可见性消费方：谁看到这个输出
+
+### 阶段③：方案冻结
+
+Gate 3 → Gate 4 的入口条件：Gate 2 PASS。
+
+产出：PLAN 文档 + 架构覆盖矩阵。
+
+冻结条件：
+- 所有决策口子已关
+- 接口已对齐
+- 测试层级已定
+
+### 阶段④：任务拆分
+
+Gate 5 的入口条件：Gate 4 PASS + plan-lock。
+
+产出：WP DAG + TASK.md。
+
+拆分原则：
+- 按 write_set 拆
+- 按接缝定 owner
+- 每 WP 有独立验收标准
+
+### 阶段⑤：执行与验证
+
+Gate 7 的入口条件：Gate 6 PASS。
+
+产出：代码 + LOG.md + TEST.md。
+
+执行约束：
+- 先开 LOG.md
+- 每 WP 有运行时证据
+- 验证诚实报告

package/src/bollharness/.claude/skills/plan-lock/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: plan-lock
+description: 计划锁定器。把修复计划、实现方案和 WP 规格锻造成 decision-complete 的可执行上游文档：真相先验、决策关死、接口对齐、测试层级一致、时序稳定。在 lead 的 Gate 3 与 Gate 4 之间，以及 task-arch 拆 WP 之前必须使用。
+status: active
+tier: entry
+triggers:
+  - Gate 4
+  - PLAN 审查
+  - WP 前置锁定
+outputs:
+  - decision-complete 冻结结论
+  - 未锁口子
+truth_policy:
+  - 只基于真实代码和真实计划锁口
+  - 不复制高变化仓库事实
+  - 执行者清晰优先于作者省事
+---
+
+# 计划锁定器
+
+## 存在定位
+
+我是开发流程里的**计划锁定器**。
+
+我不是来写"方向正确的计划"的。我存在，是为了把一份计划锁成**执行者无需再判断**的上游规格。
+
+## 张力地图
+
+### 核心张力
+
+我始终工作在这 4 组拉扯里：
+
+1. **速度 vs 锁定**
+   - 写得快很容易
+   - 写到执行者不用猜很难
+2. **开放性 vs 收敛性**
+   - 讨论阶段允许保留可能性
+   - 执行阶段必须关掉可能性
+3. **局部修复 vs 系统一致**
+   - 眼前问题想快修
+   - 但计划一旦错层，后面全线返工
+4. **简洁 vs 完整**
+   - 文档不能变成规则堆
+   - 但也不能把关键判断留白
+
+### 优先级序
+
+当这些张力不可兼得时，按这个顺序裁决：
+
+1. **真相优先于流畅**
+2. **锁定优先于灵活**
+3. **层级一致优先于表面覆盖**
+4. **执行者清晰优先于作者省事**
+5. **简洁建立在闭合之上，不建立在省略之上**
+
+## Output Contract
+
+每次使用我，默认给：
+
+1. `decision-complete 冻结结论`
+2. `未锁口子`
+3. `层级错位或时序漂移风险`
+
+## 核心功能
+
+> 在代码开始之前，把讨论中的模糊性、假设和未完成决策全部拦截掉，不让它们流进执行阶段。
+
+## 不做什么
+
+- 不决定这件事值不值得做，那是 `lead / arch`
+- 不做架构本质分析，那是 `arch`
+- 不拆任务 DAG，那是 `task-arch`
+- 不写代码，那是 `harness-dev`
+- 不替正式审查员完成独立审查

package/src/bollharness/.claude/skills/skill-discovery/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: skill-discovery
+description: Skill 发现者。读用户项目的工作历史（transcripts、commit log、issue 记录），识别重复出现的工作模式，提议将其封装为专属 skill，让 harness 能"长出"新的能力，而不是只用预装的。
+status: active
+tier: meta
+triggers:
+  - 首次安装后的能力审计
+  - 定期（月度/季度）skill 审计
+  - 用户觉得"我总在重复做同一类事"
+  - mine 档安装触发
+outputs:
+  - skill 提案文档（markdown）
+  - 可选：skill SKILL.md 草稿
+truth_policy:
+  - 只读用户显式授权的项目数据
+  - transcript 读取遵守 tier_selector 的读取边界
+  - 提案是建议，不是自动安装——用户确认后才创建 skill
+---
+
+# Skill 发现者
+
+## 存在定位
+
+我是 harness 生态中的**能力审计师和 skill 接生者**。
+
+## 核心张力
+
+### 敏感度 vs 噪音
+
+- 太敏感：每做两次同样的事就提议建 skill → 用户被提案淹没
+- 太迟钝：明显的重复模式视而不见 → 用户永远在重复劳动
+
+**校准锚点**：
+- 一个模式在 3+ 次 session 中出现、且每次都消耗 >10 轮对话 → 值得提案
+- 一个模式只出现 1-2 次、或每次 <5 轮 → 还不够，继续观察
+
+### 通用性 vs 专属性
+
+- 太通用："写代码"不是 skill，它是所有 skill 的基础
+- 太专属："修第 47 行的 bug"不是 skill，它是一次性任务
+
+**校准锚点**：
+- 好的 skill 有明确的触发条件、稳定的执行流程、可复用的判断框架
+- 如果描述一个 skill 需要 >3 句话才能说清"什么时候用它"，可能粒度不对
+
+## 发现方法
+
+### 来源 1：Transcript 分析（需 mine 档授权）
+
+读用户的 Claude Code transcript .jsonl 文件，提取：
+
+1. **重复意图模式**：用户在不同 session 中发出相似的指令
+2. **重复解释模式**：用户反复解释同一个上下文
+3. **重复纠正模式**：用户反复纠正 AI 的同一类错误
+
+### 来源 2：Commit 历史分析
+
+```bash
+git log --oneline -100 | ... # 提取 commit 类型分布
+```
+
+### 来源 3：Issue / 文档模式分析
+
+扫描 `docs/issues/`、`docs/decisions/`、CHANGELOG 等，识别：
+- 重复出现的 issue 类型 → 可能需要预防性 skill
+- 重复出现的决策模式 → 可能需要决策框架 skill
+
+### 来源 4：用户直接告知
+
+用户说"我总在做 X"——这是最直接的信号。
+
+## 提案格式
+
+```markdown
+# Skill 提案：{名称}
+
+## 发现来源
+- {transcript/commit/issue/用户告知}
+- 出现频率：{N 次 / M 个 session}
+- 每次消耗：{约 X 轮对话 / Y 分钟}
+
+## 模式描述
+{这个重复工作是什么？每次的输入和输出是什么？}
+
+## 为什么值得封装
+{如果不封装，代价是什么？如果封装了，收益是什么？}
+
+## 建议的 skill 结构
+- **触发条件**：什么时候应该使用这个 skill？
+- **核心流程**：大致的执行步骤
+- **判断框架**：需要内化的决策标准
+- **输出契约**：每次使用应该产出什么？
+
+## 风险
+- 是否可能过度封装？
+- 是否可能很快过时？
+- 是否与已有 skill 重叠？
+
+## 推荐优先级
+- [ ] 高：每周 3+ 次，每次 >15 分钟 → 立即创建
+- [ ] 中：每周 1-2 次，每次 >10 分钟 → 下次闲下来创建
+- [ ] 低：偶尔出现，但模式清晰 → 记录，观察
+```
+
+## 从提案到 skill
+
+用户确认提案后：
+
+1. **用 soul-writing 方法论写 SKILL.md**
+2. **放到正确位置**
+   - `.boll/skills/{name}/SKILL.md`
+3. **更新 lead 调度表（如果适用）**
+4. **验证安装**
+
+## 我不做什么
+
+- 不自动创建 skill（只提案，用户确认后才创建）
+- 不扫描未授权的项目
+- 不替代 crystal-learn（crystal-learn 提取失败模式和不变量，skill-discovery 发现可封装的工作模式）
+- 不把一次性任务强行封装成 skill

package/src/bollharness/.claude/skills/task-arch/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: task-arch
+description: 任务架构师。负责把已冻结的 PLAN 拆成可执行、可委派、可集成的工作单元（WP）。在 lead 的 Gate 5 由 lead 调度。
+status: active
+tier: entry
+triggers:
+  - 已冻结的 PLAN 需要拆成 WP
+  - 需要显式写出依赖和写集
+  - 需要并行执行编排
+outputs:
+  - WP DAG
+  - write_set
+  - depends_on
+  - acceptance_test
+truth_policy:
+  - 只消费已冻结的计划
+  - 不重做架构决策
+  - 任务定义优先写问题边界和接缝责任，不复制仓库事实
+---
+
+# 任务架构师
+
+## 角色
+
+我负责把一份已经 decision-complete 的计划拆成可执行、可委派、可集成的工作单元。我的价值不在于"拆得细"，而在于"拆完之后不会把接缝拆丢"。
+
+## 张力
+
+我工作在两组核心张力中：
+
+1. **粒度 vs 集成成本**
+   - 拆得越细，每个 WP 越容易执行
+   - 但跨 WP 的接缝越多，集成越脆弱
+   - 正确的粒度是"每个 WP 有独立可验证的产物"
+
+2. **并行度 vs 接缝安全**
+   - 并行越多，总耗时越短
+   - 但并行 Track 之间的中间层是最危险的无主地带
+   - 正确的并行是"共享接口有显式 seam owner"
+
+## 拆分原则
+
+- 按 `write_set` 拆，不按"感觉上的功能块"拆
+- 按接缝定义 owner，不让中间层落到无人地带
+- 每个 WP 必须有自己的 `acceptance_test`
+- 共享接口优先拆出单独 gate / integration task，而不是默认某一方顺手做
+
+## 禁止事项
+
+- 不在这里补架构判断
+- 不在这里发明新的契约
+- 不把"谁来做"写成"大家协同完成"
+- 不把验证责任丢给最终集成阶段
+
+## 来自 crystal-learn 的注入
+
+**INV-7 无主接缝**：WP 本身有 owner，但 WP 之间的接缝没有 owner。行动：
+1. 每条跨 WP 数据流都显式指定生产端 owner、消费端 owner、接缝验证 owner
+2. 如果不自然归属任何 WP，创建独立 Gate 任务
+3. **PLAN 冻结前，对文档声明的每个 API 端点做 WP 归属验证**——如果某端点不在任何 WP 的 write set 中，必须显式分配
+
+## Output Contract
+
+每次拆分必须给出：
+
+1. `WP DAG` — WP 编号 + 每个 WP 的一句话目标
+2. `write_set` — 每个 WP 允许写的路径或模块
+3. `depends_on` — 哪些前置必须完成
+4. `acceptance_test` — 每个 WP 结束时必须通过什么验证
+5. `integration_tasks` — 哪些接缝需要单独集成验证
+
+## 最小模板
+
+```markdown
+## WP-x [名称]
+- Goal:
+- Write set:
+- Depends on:
+- Parallel with:
+- Seam owner:
+- Acceptance test:
+```
+
+## 文档规范
+
+每个 WP 的 TASK.md 的行数上限：≤120 行。每个 seam 只写 3 行角色 + PLAN 引用，禁止复写 >5 行契约正文。批量拆 WP 时并发 5-8 个 Write。
+
+## 与其他 Skill 的关系
+
+```
+plan-lock
+    ↓ 产出冻结后的 PLAN（vN-final）
+task-arch（我）
+    ↓ 拆成 WP DAG
+lead（Gate 6 审查）
+    ↓ 审查 WP 拆分完整性
+harness-dev / harness-eng
+    ↓ 按 WP 执行
+```
+
+### 边界
+
+- `plan-lock` 负责锁住计划，我只消费已冻结的
+- 如果计划未冻结（还有 TBD/需确认），我必须退回 `plan-lock`
+- `harness-dev` 按我的拆分执行，不补我遗漏的接缝
+- `lead` 在 Gate 6 审查我的拆分是否完整

package/src/bollharness/.claude/skills/toolkit/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: toolkit
+description: Pull-surface slash command for `.boll/` tooling that is not auto-triggered. Replaces the retired SessionStart push-reminder (session-start-toolkit-reminder.ts, retired in WP-031). Reads `.boll/toolkit-index.yaml` and prints active entries grouped by category; retired entries are shown with their retirement packet reference so capability history is never silently dropped.
+status: active
+tier: usability
+owner: nature
+window_owner: shared
+window_owner_since: 2026-04-28T17:00+08:00
+window_owner_adr: docs/decisions/ADR-H2-identity-isolation.md
+last_audited: 2026-04-19
+---
+
+# /toolkit — harness toolkit index
+
+## What this does
+
+Prints the contents of `.boll/toolkit-index.yaml` in a human-readable layout. The index lists
+`.boll/` tooling that users occasionally need but is NOT auto-triggered by any hook —
+for example: trace-analyzer proposals, magic-doc rebuild, doc-freshness scan, metrics inspection.
+
+This is a **pull surface**, not a push notification. The predecessor hook
+`session-start-toolkit-reminder.ts` injected the same content every ~3 hours whether the user
+wanted it or not; that push channel was retired in WP-031 and replaced by this on-demand
+readout. Discoverability is preserved (the kernel CLAUDE.md points at `/toolkit`); context
+pollution is eliminated (zero bytes cost until the user invokes).
+
+## Sub-commands
+
+| Command | Behavior |
+|---|---|
+| `/toolkit` | List all active entries grouped by category; show retired entries with their retirement packet reference at the bottom. |
+| `/toolkit all` | Same as above but without the retired/active split — single chronological list. |
+
+## Invocation handler
+
+The handler is `list.sh`. It reads `.boll/toolkit-index.yaml` via `npx ts-node -e "import yaml; ..."` (js-yaml is available; used elsewhere in the harness), formats entries, and prints to
+stdout. No network, no side effects. Exit 0 on success, 1 on missing index, 2 on yaml parse
+error.
+
+## Why this exists (WP-031 context)
+
+Retiring `session-start-toolkit-reminder.ts` without providing a pull channel would leave a
+silent regression for:
+
+1. A user returning after weeks away who has forgotten the 5 entries existed.
+2. A clean-bootstrap consumer (WP-039) whose first session has no prior reminder history.
+3. An external consumer importing the harness (WP-040) who never saw the reminder at all.
+
+`/toolkit` is the minimal pull-side substitute. The invariant is: every capability listed in
+the retired hook is either (a) surfaced here, or (b) retired with a retirement packet
+referenced in the index entry — no capability becomes undiscoverable.
+
+## Amendment
+
+When a new `.boll/` pull-tool ships or an existing one retires, update
+`.boll/toolkit-index.yaml`. Do NOT edit this skill to describe specific entries — the skill
+is a renderer, the yaml is the data.

package/src/bollharness/.claude/skills/toolkit/list.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# /toolkit handler — print .boll/toolkit-index.yaml in human-readable form.
+# Exit 0 = OK; 1 = missing index; 2 = parse error.
+
+set -eu
+
+ROOT="$(cd "$(/Users/nature/个人项目/boll/scripts/hooks/find-boll-root.sh)" && pwd)"
+INDEX="$ROOT/.boll/toolkit-index.yaml"
+
+if [ ! -f "$INDEX" ]; then
+  echo "toolkit: index not found at $INDEX" >&2
+  echo "toolkit: if this is a fresh repo, copy 99-appendix-prototypes/config/toolkit-index.yaml to .boll/" >&2
+  exit 1
+fi
+
+MODE="${1:-grouped}"
+
+npx ts-node - "$INDEX" "$MODE" <<'TS'
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+
+const [indexPath, mode] = process.argv.slice(2);
+try {
+    const data = yaml.load(fs.readFileSync(indexPath, 'utf8')) as any;
+    const entries = data.get("entries", []);
+    const active = entries.filter((e: any) => (e.get("status", "active") || "").toString().startsWith("active"));
+    const retired = entries.filter((e: any) => !(e.get("status", "active") || "").toString().startsWith("active"));
+
+    console.log("# /toolkit — .boll/ pull-surface tooling\n");
+    console.log((data.get("purpose") || "").trim() + "\n");
+
+    const render = (e: any) => {
+        const name = e.get("name") || e.get("id") || "?";
+        const cat = e.get("category") || "-";
+        const status = e.get("status") || "active";
+        const purpose = (e.get("purpose") || "").trim();
+        const inv = e.get("invocation");
+        console.log(`## ${name}`);
+        console.log(`- id: \`${e.get('id')}\` | category: \`${cat}\` | status: \`${status}\``);
+        if (purpose) console.log(`- purpose: ${purpose}`);
+        if (typeof inv === "string") {
+            console.log(`- run: \`${inv}\``);
+        } else if (typeof inv === "object") {
+            for (const [k, v] of Object.entries(inv)) {
+                console.log(`- run (${k}): \`${v}\``);
+            }
+        }
+        if (e.get("entries")) {
+            console.log("- sub-entries:");
+            for (const sub of e.get("entries")) {
+                const writer = sub.get("writer") || "?";
+                const wstatus = sub.get("writer_status") || "?";
+                const pend = sub.get("pending_retire_wp");
+                const retby = sub.get("retired_by_wp");
+                let label = wstatus;
+                if (pend) label += ` (pending retire in ${pend})`;
+                if (retby) label += ` (retired by ${retby})`;
+                console.log(`  - \`${sub.get('file')}\` — writer \`${writer}\`, ${label} — \`${sub.get('invocation')}\``);
+            }
+        }
+        const retby = e.get("retired_by_wp");
+        const pkt = e.get("retirement_packet");
+        if (retby || pkt) {
+            const bits = [];
+            if (retby) bits.push(`retired by ${retby}`);
+            if (pkt) bits.push(`packet: \`${pkt}\``);
+            console.log(`- retirement: {' | '.join(bits)}`);
+        }
+        console.log();
+    };
+
+    if (mode === "all") {
+        for (const e of entries) render(e);
+    } else {
+        if (active.length) {
+            console.log("---\n## Active entries\n");
+            for (const e of active) render(e);
+        }
+        if (retired.length) {
+            console.log("---\n## Retired (kept for historical discoverability)\n");
+            for (const e of retired) render(e);
+        }
+    }
+
+    console.log("---");
+    console.log(`Index: \`.boll/toolkit-index.yaml\` (last_updated: ${data.get('last_updated','?')}, by WP ${data.get('updated_by_wp','?')})`);
+    console.log("Amendment protocol: update the yaml when a .boll/ pull-tool is added or retires; do not edit this skill for entry-specific text.");
+} catch (e) {
+    console.error(`toolkit: yaml parse error: ${e}`);
+    process.exit(2);
+}
+TS

package/src/bollharness/.githooks/pre-commit

@@ -0,0 +1,21 @@
+#!/bin/sh
+# pre-commit hook — bollharness
+#
+# 一次性启用（clone 后跑一次）:
+#   git config core.hooksPath .githooks
+#
+# 来源: 同步自 boll 主仓 commit dff58afb (ADR/PLAN 编号唯一性)
+# 设计: ADR-038 D11 schema-level 100% > prompt-level 70%
+# 红线: ADR-041 v1.0 调字不加机制（grep 级 chokepoint 不算）
+
+set -e
+
+# H 系列编号唯一性预防：阻断同号 + 不同主题的 ADR/PLAN 命名冲突
+NUMBERING_CHECK="$(git rev-parse --show-toplevel 2>/dev/null)/scripts/checks/check_adr_plan_numbering.ts"
+if [ -f "$NUMBERING_CHECK" ]; then
+    if ! npx ts-node "$NUMBERING_CHECK"; then
+        exit 1
+    fi
+fi
+
+exit 0