@bolloon/bolloon-agent 0.1.0

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

@@ -0,0 +1,91 @@
+# 审查闭环 SOP
+
+lead skill 的审查操作手册。审查是每个阶段的硬门禁。
+
+---
+
+## 核心原则
+
+每个阶段结束后必须审查。审查用 TeamCreate（独立上下文 = 不被已有讨论污染的判断）。不是 Agent tool（subagent），是持久化 Team。
+
+## 审查何时触发
+
+```
+① 讨论沉淀 → ✅ 审查：本质找对了吗？
+② 决策书 ADR → ✅ 审查：决策完备吗？
+③ 接口设计 → ✅ 审查：契约清楚吗？消费方覆盖了吗？
+④ 实现方案 PLAN → ✅ 审查：方案能实现计划吗？
+  ④-a 任务拆分 WP → ✅ 审查：WP 完备、解耦、可执行吗？
+⑤ 代码实现 → ✅ 审查：每个 WP 完成后单独审查
+⑥ 集成验收 → ✅ 审查：端到端走通吗？
+```
+
+## 标准审查流程
+
+```
+TeamCreate("review-{plan-id}")
+
+第 1 轮：多视角独立审查（Team 内并行）
+├── Teammate A：视角 1
+├── Teammate B：视角 2
+└── Teammate C：视角 3
+
+↓ 收集独立报告 → 汇总 → 修正 → 再审 → 通过
+```
+
+## 审查维度矩阵
+
+| 阶段 | 视角 A | 视角 B | 视角 C |
+|------|--------|--------|--------|
+| ① 讨论 | 商业可行性 | 技术本质 | 用户体验 |
+| ② ADR | 选项完备性 | 架构一致性 | 风险分析 |
+| ③ 接口 | 消费方完备 | 向后兼容 | 可测试性 |
+| ④ PLAN/WP | 代码现状验证 | 任务解耦+依赖 | 测试+验收可执行 |
+| ⑤ 代码 | 功能正确性 | 安全+错误处理 | 性能+生产就绪 |
+| ⑥ 集成 | 端到端链路 | 回归验证 | 部署就绪 |
+
+## PLAN-033 教训：审查团队扩展维度
+
+**Gate 4（PLAN 审查）必须额外覆盖**（详见 `plan-lock/ref-three-checks.md`）：
+
+| 维度 | 检查什么 |
+|------|---------|
+| C. 消费方语义兼容 | 接口变更后所有调用方在新语义下行为正确 |
+| D. 数据流完整性 | 新字段从创建到消费的传递链无断点 |
+| E. 时间边界 | 跨午夜/跨过期/并发竞态 |
+| F. 对抗/红队 | 攻击者能构造什么输入获得不正当利益 |
+
+## 生产问题诊断硬规则（2026-03-18 沉淀）
+
+**当审查对象是"生产故障"时，审查的第一步不是看代码，是看生产证据。**
+
+| 顺序 | 动作 | 不是 |
+|------|------|------|
+| 1 | 看日志、事件、DB 中的实际错误 | 看代码猜"可能哪里错了" |
+| 2 | 对比成功 case 和失败 case 的时间线 | 从代码结构推断"应该用另一种方式" |
+| 3 | 验证运行环境（认证、权限、沙盒、磁盘） | 假设环境和本地一样 |
+| 4 | 最后看代码，只为理解机制 | 把"代码可以改进"等同于"这里是 bug" |
+
+**Gate 0 的额外检查项**（生产故障类 issue）：
+- [ ] 是否已查看失败 run 的实际错误消息（不是推测）
+- [ ] 是否已对比同路径下的成功 run
+- [ ] 是否已验证运行环境与本地的差异
+
+## WP 拆分专项审查
+
+当 PLAN 拆分成 WP 后，逐条检查：
+
+1. **PLAN 覆盖率** — 每个 RP 在 WP 中都有归属
+2. **WP 解耦与依赖** — 依赖正确，并行度最大化
+3. **代码现状验证** — 文件/函数签名与真实代码一致
+4. **接缝完整性** — 没有"不属于任何 WP 的中间层"
+5. **验收可测试性** — 每个 WP 有可自动化的验收标准
+6. **执行分配** — 每个 WP 由哪个 Skill 负责
+
+## 日志要求
+
+每次审查产生日志：`docs/decisions/tasks/{WP-ID}/LOG.md`。
+
+## Skill 自迭代
+
+审查中发现的可复用教训，沉淀到对应 Skill 的 reference 文件中，不只是 memory。

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

@@ -0,0 +1,129 @@
+# 开发阶段详细描述
+
+lead skill 的 5 个阶段的深度定义。主 SKILL.md 的 Gate 0-8 是强制顺序，这里是每个阶段的详细操作指南。
+
+---
+
+## 阶段 ①：讨论沉淀
+
+**目标**：把想法想清楚，找到本质。
+
+**必须加载**：`arch` skill（架构师做本质分析，不是 lead 自己想）
+
+**做什么**：
+- 从架构原则出发分析（引用 `docs/architecture/DESIGN.md` 的具体 Section）
+- 列出多个方案和 trade-off，不只给一个答案
+- 追问"这个东西的本质是什么？它属于哪一层？"
+- 识别它是**契约变更**还是**实现变更**
+- 记录讨论中达成的共识
+
+**消费方发现门禁**（必须在讨论阶段完成，三个维度都要覆盖）：
+```
+数据消费方（谁在读这个实体的数据）：
+□ 这个 Feature 改动涉及哪些组件/模块？
+□ 每个被改组件有哪些消费方？（grep import 来源）
+□ 消费方 > 1 时，所有消费方都在 Feature scope 内吗？
+□ 不在的消费方：纳入 scope，或显式标注"不受影响 + 原因"
+
+行为消费方（谁在调用这个实体的能力）：
+□ 这个实体被创建/注册后，系统中谁会调用它的方法/能力？
+□ 每个调用点，实体的状态是否足以支持调用？（如 adapter!=None 才能 chat）
+□ "接口接受" ≠ "语义完整"——API 接受你的输入不代表产物是完整公民
+
+可见性消费方（谁在查找/匹配这个实体）：
+□ 这个实体在所有 scope/query 条件下都能被找到吗？
+□ 有没有过滤条件会让它隐形？（如空 scene_ids → 场景查询不可见）
+```
+**原则**：Feature scope = 改动集 ∪ 改动的所有消费方（数据+行为+可见性三维）。scope 不由"我想做什么"决定，由"谁在用我改的东西"决定。
+
+**不做**：不跳到"怎么实现"。这个阶段只讨论"是什么"和"为什么"。
+
+---
+
+## 阶段 ②：决策书 (ADR)
+
+**目标**：把共识变成正式决策，留下记录。
+
+**门禁**：阶段 ① 的讨论已充分，核心问题已回答。
+
+**必须加载**：`arch` skill
+
+**做什么**：
+- 写 `docs/decisions/ADR-NNN-xxx.md`
+- 格式：背景 → 选项分析（≥2 个方案 + trade-off）→ 决策 → 核心原则 → 影响范围
+
+**不做**：不在 ADR 里写实现细节。ADR 描述"做什么决定"，不描述"怎么实现"。
+
+---
+
+## 阶段 ③：接口设计
+
+**目标**：定义功能的**本质**——它做什么，不是怎么做。
+
+**门禁**：ADR 已获批准。
+
+**必须加载**：`arch` skill + 领域相关 Skill
+
+**做什么**：
+- 定义输入/输出的语义
+- 定义调用方和实现方之间的契约
+- 定义操作会产生的事件/状态变化
+- 与现有契约的关系
+
+**本质描述的标准**：换一种实现方式，接口定义不需要改。
+
+---
+
+## 阶段 ④：实现方案 (PLAN)
+
+**目标**：把接口设计映射到代码改动。
+
+**门禁**：接口设计已完成，且架构设计审查 blocker 已清零。
+
+**必须加载**：`harness-eng` + 领域 Skill + `plan-lock`
+
+**做什么**：
+- 写 `docs/decisions/PLAN-NNN-xxx.md`
+- 列出具体要改/新增的文件
+- 每条变更链路追踪到底
+- 架构覆盖矩阵：逐条核对"架构设计 → PLAN 承载"
+- **冻结步骤**：必须经过 `plan-lock` 关掉所有决策口子
+
+**变更链路追踪清单**：
+```
+□ 我改的是契约还是实现？
+□ 如果是契约，消费方有哪些？列出来。
+□ 数据从哪来 → 经过哪些层 → 到哪去？每一层有代码吗？
+□ 有没有降级路径？降级路径也通了吗？
+□ 有没有"不归任何人"的中间层？
+```
+
+**消费方验证清单**：
+```
+数据消费方：每个都有对应的变更条目吗？降级路径覆盖了吗？
+行为消费方：复用已有模式时，原模式的语义意图适用于新场景吗？
+可见性消费方：新实体在所有 scope 查询下都可见吗？
+```
+
+**硬性规则**：只有标成 `vN-final` 的冻结计划，才允许进入审查或交给 `task-arch`。
+
+---
+
+## 阶段 ⑤：代码实现
+
+**目标**：按方案写生产级代码。
+
+**强制 Skill 调度**：
+
+| 领域 | Skill | 什么时候用 |
+|------|-------|-----------|
+| 全栈实现（默认） | `harness-dev` | 跨前后端改动、调试、重构 |
+| 状态机/编排 | `arch` + `harness-eng` + `harness-dev` | 需要先冻结状态语义，再落执行编排和实现 |
+| LLM/Prompt | `soul-writing` + `harness-dev` | 行为文本设计、tool-use、parser 落地 |
+| HDC/向量 | `arch` + `harness-lab` | 编码策略、共振实验、证据化验证 |
+| 前端 UI | `harness-eng-frontend` | 组件、WS 事件消费 |
+| 前端设计 | `nature-designer` | 视觉设计、交互 |
+| 测试 | `harness-eng-test` | 测试策略 |
+| 架构对齐 | `arch` | 可能违反架构原则时 |
+
+**快速通道可以跳阶段，不可以跳 Skill。**

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

@@ -0,0 +1,169 @@
+---
+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 接生者**。
+
+大多数 skill 是预装的——arch、plan-lock、guardian-fixer 这些通用治理能力。但每个项目都有自己独特的重复工作模式：某种特定的代码审查视角、某种特定的文档格式、某种特定的部署流程、某种特定的客户沟通方式。
+
+这些模式如果一直以"每次重新解释一遍"的方式存在，就是在浪费 context window 和用户耐心。把它们封装成 skill，就把隐性知识变成了可重用的显性能力。
+
+**我不是自动化工厂**——我不会未经用户同意就创建 skill。我是**发现者和提案者**。我找到模式，写成提案，用户决定是否采纳。
+
+## 核心张力
+
+### 敏感度 vs 噪音
+
+- 太敏感：每做两次同样的事就提议建 skill → 用户被提案淹没
+- 太迟钝：明显的重复模式视而不见 → 用户永远在重复劳动
+
+**校准锚点**：
+- 一个模式在 3+ 次 session 中出现、且每次都消耗 >10 轮对话 → 值得提案
+- 一个模式只出现 1-2 次、或每次 <5 轮 → 还不够，继续观察
+
+### 通用性 vs 专属性
+
+- 太通用："写代码"不是 skill，它是所有 skill 的基础
+- 太专属："修第 47 行的 bug"不是 skill，它是一次性任务
+
+**校准锚点**：
+- 好的 skill 有明确的触发条件、稳定的执行流程、可复用的判断框架
+- 如果描述一个 skill 需要 >3 句话才能说清"什么时候用它"，可能粒度不对
+
+### 封装 vs 自由
+
+- 过度封装：把灵活的工作流程硬塞进僵硬的模板 → 用户觉得被束缚
+- 不够封装：每次都从零开始 → 用户觉得在重复劳动
+
+**校准锚点**：
+- skill 应该封装**判断框架和执行流程**，不封装**具体内容**
+- 用户应该觉得"这个 skill 帮我省了思考"，不是"这个 skill 替我做了决定"
+
+## 发现方法
+
+### 来源 1：Transcript 分析（需 mine 档授权）
+
+读用户的 Claude Code transcript .jsonl 文件，提取：
+
+1. **重复意图模式**：用户在不同 session 中发出相似的指令
+   - 例："帮我审查这个 PR 的安全性" 出现 5+ 次 → 可能需要安全审查 skill
+   - 例："按我们的格式写 changelog" 出现 3+ 次 → 可能需要 changelog skill
+
+2. **重复解释模式**：用户反复解释同一个上下文
+   - 例：每次做 deployment 都要解释"先 build，再 scp，再 restart systemd" → 部署 skill
+   - 例：每次写文档都要解释"我们用的是 ADR 格式" → 文档规范 skill
+
+3. **重复纠正模式**：用户反复纠正 AI 的同一类错误
+   - 例：反复说"不要用暗色主题" → 这个约束应该在某个 skill 里
+   - 例：反复说"commit 要双语" → 这个约束应该在某个 skill 里
+
+### 来源 2：Commit 历史分析
+
+```bash
+git log --oneline -100 | ... # 提取 commit 类型分布
+```
+
+如果某类 commit（如 "fix: ...", "docs: ...", "deploy: ..."）占比 >30%，说明这类工作是高频的，可能值得 skill 化。
+
+### 来源 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**
+   - 张力三角：这个 skill 存在于什么张力中？
+   - 判断人格：面对灰度区域，这个 skill 用什么启发式判断？
+   - 双向校准：什么算做得太多？什么算做得太少？
+   - 反面命名：这个 skill 的典型失败模式叫什么？
+
+2. **放到正确位置**
+   - `.boll/skills/{name}/SKILL.md`
+
+3. **更新 lead 调度表（如果适用）**
+   - 如果新 skill 应该在某个 Gate 被调度，更新 lead/SKILL.md
+
+4. **验证安装**
+   - 用一个真实场景触发新 skill，确认它能正确激活并产出预期结果
+
+## 定期审计节奏
+
+- **首次安装后**：跑一次完整发现（来源 1-4），产出 3-5 个提案
+- **每月**：快速扫描最近 transcript，看有没有新的重复模式
+- **每季度**：审计已有 skill 的使用频率，低频 skill 考虑归档
+
+## 我不做什么
+
+- 不自动创建 skill（只提案，用户确认后才创建）
+- 不扫描未授权的项目（严格遵守 tier_selector 读取边界）
+- 不替代 crystal-learn（crystal-learn 提取失败模式和不变量，我发现可封装的工作模式）
+- 不把一次性任务强行封装成 skill
+
+## 与其他 Skill 的关系
+
+| Skill | 关系 |
+|-------|------|
+| `crystal-learn` | 互补——crystal-learn 发现失败模式和不变量，skill-discovery 发现可封装的工作模式 |
+| `lead` | 消费者——新 skill 可能需要加入 Gate 调度表 |
+| `arch` | 咨询——新 skill 的设计是否与项目世界观一致 |
+| `harness-voice` | 咨询——新 skill 涉及对外表达时需要 voice 的语言 DNA |

package/src/bollharness/.boll/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 的关系
+
+```text
+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/.boll/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; ..."` (yaml parser 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/.boll/toolkit-index.yaml

@@ -0,0 +1,112 @@
+schema_version: "1.0"
+purpose: |
+  Pull-surface index of .boll/ tooling that is not auto-triggered by hooks. Replaces the
+  SessionStart push-reminder (session-start-toolkit-reminder.ts, retired WP-031). A new
+  operator — human or external consumer importing the substrate in WP-040 — can discover
+  these capabilities via `/toolkit` without needing to grep the repo.
+last_updated: "2026-04-19"
+updated_by_wp: "WP-032"
+
+entries:
+  # Entry #1 from the retired reminder. trace-analyzer still writes proposals; this is the read side.
+  - id: trace-analyzer-proposals
+    name: "Review trace-analyzer proposals"
+    category: proposals
+    status: active
+    purpose: |
+      SessionEnd trace-analyzer.ts writes findings under .boll/proposals/ but does not act on
+      them. High-confidence (>= 0.8) findings warrant opening an issue under docs/issues/.
+    invocation: "ls -lt .boll/proposals/ | head -5"
+    source_hook: ".boll/settings.json SessionEnd → scripts/hooks/trace-analyzer.ts analyze"
+    notes: |
+      Silent when empty. If anything listed, read the file, and if confidence >= 0.8 open an
+      issue ticket or a retirement packet depending on the finding type.
+
+  # Entry #2. Script still exists; receiver was only the reminder before.
+  - id: magic-doc-rebuild
+    name: "Rebuild magic docs (after source changed)"
+    category: docs
+    status: active
+    purpose: |
+      Rebuilds auto-generated documentation from source-of-truth inputs. Run when you've
+      changed a file that feeds a magic doc (check_doc_freshness will tell you which).
+    invocation:
+      rebuild: "npx ts-node scripts/checks/regenerate_magic_docs.ts all"
+      check_only: "npx ts-node scripts/checks/regenerate_magic_docs.ts all --check"
+    source_script: "scripts/checks/regenerate_magic_docs.ts"
+
+  # Entry #3.
+  - id: doc-freshness-check
+    name: "Full doc freshness scan"
+    category: docs
+    status: active
+    purpose: |
+      Detects drift between source inputs and magic docs across the repo.
+    invocation: "npx ts-node scripts/checks/check_doc_freshness.ts"
+    source_script: "scripts/checks/check_doc_freshness.ts"
+
+  # Entry #4. The capability itself is retired on the vNext path.
+  - id: mid-task-recitation-tuning
+    name: "Tune D9 mid-task recitation frequency"
+    category: legacy
+    status: retired_on_vnext_path
+    retired_by_wp: "WP-030"
+    retirement_packet: ".boll/evidence/wp-030/retire-tool-call-counter.json"
+    purpose: |
+      Historically: `export BOLL_RECITATION_EVERY=N` tuned the interval at which
+      tool-call-counter.ts injected constitutional recitations. The reciter was retired in
+      WP-030 (replaced by pointer-based precompact.sh, WP-028). On the vNext path this env
+      var is a no-op. Legacy .boll/ sessions still honor it until Phase G full cutover.
+
+  # Entry #5. Mixed status — each sub-file re-evaluated.
+  - id: harness-metrics-view
+    name: "Inspect cumulative metrics"
+    category: metrics
+    status: active_with_retirements_in_flight
+    purpose: |
+      Read-only inspection of metrics that v5 hooks write under .boll/metrics/. Some writers
+      have retired; their files stop updating but remain for historical inspection.
+    entries:
+      - file: ".boll/metrics/tool-call-counter.txt"
+        writer: "tool-call-counter.ts"
+        writer_status: retired_on_vnext_path
+        retired_by_wp: "WP-030"
+        invocation: "cat .boll/metrics/tool-call-counter.txt"
+        notes: "File frozen on vNext; legacy sessions still append."
+
+      - file: ".boll/metrics/guard-events.jsonl"
+        writer: "guard-feedback.ts"
+        writer_status: active
+        invocation: "wc -l .boll/metrics/guard-events.jsonl"
+
+      - file: ".boll/metrics/stop-events.jsonl"
+        writer: "stop-evaluator.ts"
+        writer_status: active_pending_retirement
+        pending_retire_wp: "WP-033"
+        invocation: "wc -l .boll/metrics/stop-events.jsonl"
+
+      - file: ".boll/metrics/tool-failures.jsonl"
+        writer: "failure-analyzer.ts"
+        writer_status: retired_on_vnext_path
+        retired_by_wp: "WP-032"
+        retirement_packet: ".boll/evidence/wp-032/retire-failure-analyzer.json"
+        invocation: "wc -l .boll/metrics/tool-failures.jsonl"
+        notes: "File frozen on vNext; replaced by evidence-emit.ts step-packet blockers. Legacy sessions still append."
+
+      - file: ".boll/metrics/initializer-events.jsonl"
+        writer: "capability-router.ts (or wp-init path)"
+        writer_status: active
+        invocation: "wc -l .boll/metrics/initializer-events.jsonl"
+
+discoverability_contract: |
+  A consumer who knows nothing about this substrate should be able to invoke `/toolkit` and
+  learn the full surface of .boll/ pull-tooling. Every entry is either (a) active and
+  actionable or (b) explicitly retired with a pointer to the retirement packet — there is no
+  "dead link" state. When a writer retires, the corresponding entry here flips to a retired
+  status with retired_by_wp and retirement_packet filled; do not silently delete entries.
+
+amendment_protocol: |
+  Add an entry when a new .boll/ pull-tool ships (new script, new metrics file, new proposal
+  channel). Flip an entry to retired when its writer retires, keeping the historical record.
+  This file is NOT source-of-truth for what's active — the retirement packets in
+  .boll/evidence/ are. This file is a navigation index that points at those truths.