@bolloon/bolloon-agent 0.1.0

package/src/bollharness/docs/decisions/ADR-H4-prompt-governance.md

@@ -0,0 +1,146 @@
+# ADR-H4: Prompt 治理（行为偏好三类清单：黑话 / 推卸 / 过度 review）
+
+**状态**：Draft（待 reviewer 复核后转 Accepted；H 系列拓扑 D 第 5 个 ADR）
+**日期**：2026-04-28
+**关联**：ADR-H0 元规约 / ADR-H2 身份隔离 / ADR-H9 inbox 邮箱 / ADR-H3 memory scope / ADR-041 Codex 分流 v1.0 / ADR-038 D11 schema-level 隔离 / `.boll/skills/lead/SKILL.md`
+
+## 1. 决策本质
+
+把跨 session 反复出现的"行为偏好类违规"（黑话 / 推卸决策 / 过度 review）从**散落在 6 条 memory feedback** 升级为 **lead SKILL.md 内一段 ≤30 行 checklist**，让 lead skill 加载时直接推入 prompt context；触发 70% 遵从率（ADR-038 D11.2 prompt-level 兜底基线，schema 隔离不适用——这是行为偏好，不是工具调用边界）。
+
+> **H4 = 把已经存在但散落的教训聚拢成 lead skill 上的清单**，不是发明新规则。
+> ADR-041 v1.0 已签"老板心态 + 红线 + 每周复盘"哲学——本 ADR 是其在"语言/对话表达"侧的具体化。
+
+## 2. 不变量（INV-H4）
+
+- **INV-H4-1（清单最小厚度）**：`.boll/skills/lead/SKILL.md` 内必须存在一段 `## 行为治理（H4 三类清单）` 或同义标题，含 **≥10 条** checklist 项（每条 1 行：触发场景 → 应有行为 → memory pointer）
+- **INV-H4-2（pointer 强制）**：每条 checklist 必须挂 `feedback_*.md` 真相源 pointer；不允许新建无 pointer 的"凭空规则"（避免 ADR-041 v0.1 → v0.3 inflation 重演）
+- **INV-H4-3（哲学边界硬规）**：H4 **不**写任何 hook、**不**加 metrics、**不**动 `review-contract.yaml`、**不**改 PreToolUse / PostToolUse / SessionStart hook 链路（schema-level 治理是 H2/H7/H6 段范畴；H4 严格留在 prompt-level）
+
+## 3. 设计
+
+### 3.1 三类清单（H4 最小集合）
+
+按现有 6 条 memory feedback 教训映射到 3 个语义类：
+
+| 类别 | 触发场景 | 应有行为 | memory pointer |
+|------|---------|---------|---------------|
+| **黑话** | 跟 Nature 对话中即将冒出 idle / commit / SendMessage / pytest / PASS / verify / spawn 等术语 | 改用人话（"等一下" / "保存进度" / "跟队友说一声" / "跑测试" / "通过" / "验证" / "派人去做"）；保留协议术语仅在 ADR/PR 内部 | `feedback_no_jargon_with_nature.md` |
+| **黑话（task-arch）** | 起草 task-arch 文档时倾向把每个 seam 契约逐字复写 | 每 seam 只 3 行角色 + PLAN 引用 | `feedback_task_arch_verbose_rewrite.md` |
+| **推卸（反问）** | 收到不熟悉的需求时第一反应是反问"你确认要 X 吗？" | 拿不准就派 teammate 或先做现状 grep；不要把决策权抛回 Nature | `feedback_stop_asking_confirmation.md` / `feedback_answer_not_ask.md` / `feedback_delegate_to_teammate_on_uncertain.md` |
+| **推卸（待协调员决定）** | 起草 ADR/PLAN 时倾向写"待协调员决定 / TBD / 后续讨论" | 直接给当下最佳判断；H0.4 自指禁止已物理化此规则 | `feedback_stop_asking_confirmation.md`（升级版） |
+| **过度 review（review-driven inflation）** | reviewer 给 P1/P2 时第一反应是大重构 / 加新机制 / 写 hook 拦截 | 先调规则文字（ADR-041 哲学）；机制化必须先在每周复盘里证明"调规则解决不了" | `feedback_review_driven_complexity_inflation.md` |
+| **过度 review（同维度反复）** | 同一 PR 第 N 轮 review 时给同一维度建议 | 多轮同维度 = 边际递减；换正交方法论 | `feedback_review_methodology_orthogonal.md` |
+| **过度 review（无证宣告 PASS）** | reviewer 给 PASS 但子项 P0 未闭 | 任何 PASS_WITH_NOTES 含 P0 仍为 BLOCK；修复后必须重评估 | `lead/SKILL.md` 现有段（已存）|
+| **完工虚报** | 实现完成即宣告 done，未跑 E2E / 未截图 | E2E + Playwright + 真实后端是 Gate 7→8 必经 | `feedback_e2e_before_push.md` |
+| **起草未实证（H 系列 dogfood）** | 起草 ADR/PLAN 引用受管资产时未先 wc / grep / ls 实证 | 起草前必做 4 项核：路径存在 + 行数 + frontmatter 字段 + 前置 ADR 已覆盖 | `.boll/log/harness-self-symptoms.md` §4.7 / §4.8 |
+| **结论范围越界** | 单点测试 PASS 即宣告全量 PASS / 平台级声明 | 测试 ≤ docstring ≤ LOG ≤ commit；平台级前核 vendor docs | `feedback_assertion_scope_discipline.md` |
+
+合计 **10 条**，正好达成 INV-H4-1 最小厚度。新增条目按 INV-H4-2 必须挂 pointer。
+
+### 3.2 lead SKILL.md 集成位置
+
+在 lead/SKILL.md 现有"### Gate 7 开发日志硬性要求"段**之后** + "## 联动规则（skill 调度表）"段**之前**插入新段：
+
+```markdown
+## 行为治理（H4 三类清单）
+
+> 本段由 ADR-H4 物理化 6 条 memory feedback 教训。lead skill 加载时直接推入 prompt context（70% 遵从率基线，schema 隔离不适用）。
+> 任何 checklist 项升级或新增按 INV-H4-2 挂 memory pointer，禁止凭空规则。
+
+### 黑话
+- ...
+
+### 推卸
+- ...
+
+### 过度 review
+- ...
+```
+
+### 3.3 与 ADR-041 v1.0 的关系（重要）
+
+ADR-041 v1.0 §3 已签"先调规则不加机制"哲学；本 ADR **完全继承**该哲学：
+
+| 维度 | ADR-041 v1.0 | ADR-H4 |
+|------|--------------|--------|
+| 治理对象 | Codex 分流决策（"是否派 Codex"） | 表达行为（"怎么说话"） |
+| 物理介质 | CLAUDE.md §零 + ADR-041 §3 红线 | lead/SKILL.md `## 行为治理`段 |
+| 机制化禁令 | hook / router / metrics 全砍 | 同砍（INV-H4-3）|
+| 升级路径 | 每周复盘人脑回顾 | 同（H4 不另立机制） |
+
+H4 是 ADR-041 在不同行为侧（决策 vs 表达）的孪生子，**不重复也不冲突**。
+
+### 3.4 与 H5 边界（plan §3.3.1）
+
+| 维度 | H4 (本 ADR) | H5 (未来) |
+|------|-------------|-----------|
+| 范围 | lead / arch / boll-dev SKILL.md prompt 段 | review-contract.yaml + Gate 清单 + .boll/skills/boll-review/ |
+| 介质 | 纯 markdown 文字 | yaml + 文档 |
+| 触发 | skill 加载时 prompt context | Gate 流转时 contract spawn reviewer |
+| 治理对象 | 表达行为 | 节奏控制（review 轮次 / inflation 规则） |
+
+二者**不交叉**：H4 不动 review-contract，H5 不动 SKILL.md prompt 段。如某条规则跨界（既要 prompt 又要 yaml），按 plan §3.3.1 串行：先 H4 prompt，再 H5 yaml backport。
+
+### 3.5 受管资产 scope（H0.1 施工隔离）
+
+| 路径 | 动作 |
+|------|------|
+| `docs/decisions/ADR-H4-prompt-governance.md` | 新增（本文件） |
+| `docs/decisions/PLAN-H4-prompt-governance.md` | 新增（PLAN 起草） |
+| `.boll/skills/lead/SKILL.md` | 追加 `## 行为治理` 段（≤30 行）|
+| `docs/decisions/tasks/PLAN-H4/demo-rewrite-{ts}.md` | 1 个 demo 改写示范（PLAN-H4 §2 WP-04）|
+| `docs/decisions/tasks/PLAN-H4/reviewer-verdict-*.md` | reviewer 落点 |
+| `.boll/log/harness-self-symptoms.md` | append §4.x（如有自指）|
+
+**不动**：ownership.yaml / hook / review-contract.yaml / arch SKILL.md（暂不改 — PLAN-H4 WP-01 盘点确认现状再定）/ boll-dev SKILL.md / 任何业务代码。
+
+### 3.6 失败模式（必须 inline，不留撞坑）
+
+**FM1**：lead SKILL.md 加上"## 行为治理"段后膨胀超 200 行 → 触发与 INV-H3-1 同类的物理 truncate 风险。
+**对策**：H4 段 ≤30 行硬规（INV-H4-1 上限附加值）；超限按 INV-H3-2 双层口径分拆。
+
+**FM2**：H4 写入后被 reviewer 当作 inflation 攻击面 → 重演 ADR-041 v0.1→v0.3 失败模式。
+**对策**：每条 checklist 强制挂 memory pointer（INV-H4-2）；reviewer 反对必须指认"哪条规则没 pointer"，否则属同维度反复 review（H4 §3.1 第 6 条命中）。
+
+**FM3**：跨 SKILL.md 复制粘贴（lead → arch → boll-dev）导致同规则三个副本漂移。
+**对策**：H4 仅在 lead/SKILL.md 落地；其他 skill 引用时用 pointer 不复制（lead skill 是 entry tier，所有 session 必加载，不需要在 arch/boll-dev 重复）。
+
+## 4. 反对意见与取舍
+
+**反对 1**：lead SKILL.md 已经 169 行 + 加 30 行 = 199 行，逼近 200 行 truncate 阈值（INV-H3-1 同类）。
+
+**取舍**：lead SKILL.md 不是 user-level memory（在 `.boll/skills/lead/`，不受 200 行 truncate 限制；CC skill 加载是按完整文件读，无 line-cutoff）。reviewer 若担心 prompt context token 占用，按 ADR-041 §3 "先调规则不加机制" — 不引入 hook 切片；如未来某段冗余，按 INV-H4-2 删冗余条目（每条必须挂 pointer = 必然有真相源备份）。
+
+**反对 2**：行为偏好治理本质是"语气问题"，靠 prompt 70% 遵从率 = 30% session 仍然违规；该升级到 hook 拦截。
+
+**取舍**：ADR-038 D11 已明确："prompt 解决不了语气问题，schema 也解决不了"。70% 是行为偏好上限；剩 30% 靠 Nature 每周复盘人脑回顾（继承 ADR-041 路径）。任何 hook 拦截"黑话"都会撞 false-positive 海啸（"commit"二字在工程上下文必然出现，hook 无法区分"对 Nature 说 commit"vs"在 ADR 里写 commit"）。
+
+**反对 3**：H4 只做 lead SKILL.md = 漏覆盖 arch / boll-dev 等其他 skill 加载时的违规。
+
+**取舍**：lead 是 entry tier，CLAUDE.md 隐式默认加载；其他 skill 是按需加载。70% 遵从率基线建立在"必读 skill"的位置；arch/boll-dev session 已经有 lead 加载，规则会跨级生效。如未来发现 arch session 的违规率显著高于 lead session，按 ADR-041 路径："先调规则文字" — 在 lead `## 行为治理`段加 1 条"在 arch 子任务中同样适用"，不复制清单。
+
+## 5. ADR-H0 元规约自检
+
+- **H0.1 施工隔离**：scope 列表见 §3.5（6 类路径，全在 `docs/decisions/`、`docs/decisions/tasks/`、`.boll/skills/lead/`、`.boll/log/`）
+- **H0.2 节流限速**：本 ADR 目标 ≤ 300 行（终稿见 wc -l）；PLAN-H4 ≤ 500 行
+- **H0.3 执检分离**：起草 = 本 session；reviewer 必为非起草 read-only subagent（PLAN-H4 末位 WP）
+- **H0.4 自指禁止**：H4 修"黑话/推卸/过度 review"，本 ADR grep `TBD|后续讨论|待协调员决定` 仅元层定义命中（参 ADR-H0 §6 例 4 + §3.1 #4 推卸类条目本身就是定义）
+- **H0.5 跨子计划协调**：lead/SKILL.md 共改冲突已记入 H 系列 plan §3.4 冲突表（H2 × H4 串行；H2 已 merged，H4 后续在新 schema 上加段不冲突）
+- **H0.6 证据机械化**：所有 INV / DoD 给 grep / wc / `find` 命令（详 PLAN-H4 §2 verify 命令段）
+- **H0.meta**：本 ADR 自身不引用 H1/H5/H6/H8 未来产物（grep `\bH[1568]\b` 仅本检查行 + §3.4 H5 边界段命中）
+
+## 6. 关系
+
+- **ADR-H0 §3 元规约**：本 ADR 完全遵守 H0.1-H0.6 + H0.meta（自检见 §5）
+- **ADR-H3 INV-H3-2 v1.1 双层限速**：lead SKILL.md 不是 MEMORY.md，不受 200 行 truncate 限制；本 ADR §4 反对 1 已答辩
+- **ADR-038 D11.2 prompt-level 兜底基线**：H4 完全在 prompt-level 工作，70% 遵从率是 D11.2 给定上限
+- **ADR-041 v1.0 §3 不做的事**：H4 完全继承 §3 哲学，不写 hook / router / metrics（INV-H4-3）
+- **PLAN-H4-prompt-governance.md**：本 ADR 工程实施真相源
+- **lead/SKILL.md 现有段**：H4 新段插入位置详 §3.2
+
+## 7. 落地范围 + DoD
+
+- 详细 WP 拆解 + DoD：见 PLAN-H4 §2
+- H 系列 plan §3.3 H4 行：3 天估时；DoD 关键 = checklist ≥ 10 + 自指悖论显式段 + 自身 grep "TBD\|后续讨论" = 0 + 1 个 demo 改写
+- 末位 reviewer 签字：H0.3 执检分离强制

package/src/bollharness/docs/decisions/ADR-H5-gate-quantization.md

@@ -0,0 +1,212 @@
+---
+adr: ADR-H5
+title: Gate 量纲化（行数硬限 schema 化 + 执检分离 binding 化 + 跳 Gate 决策表）
+status: accepted
+date: 2026-04-28
+parent_charter: ADR-H0-meta-charter.md
+philosophy_inheritance:
+  - ADR-041-codex-integration v1.0（"调字不加机制"）
+  - ADR-H4 INV-H4-3 反例表第 2 条（不写 metrics / 不写 dashboard / 不写 hook 治节奏）
+  - ADR-038 D11.2（schema-level 100% 遵从 >> prompt-level 70%）
+applies_scope:
+  - .boll/plugins/boll-review-toolkit/contracts/review-contract.yaml
+  - .boll/plugins/boll-review-toolkit/agents/reviewer.md（仅引用，不改）
+  - 本 ADR 自身（自指 dogfood）
+not_in_scope:
+  - .boll/skills/lead/SKILL.md（H4 占位；本 H 不动）
+  - 任何新 hook（INV-H5-3 红线）
+  - .boll/state/ 下新增 metrics 文件（INV-H5-3 红线）
+---
+
+# ADR-H5：Gate 量纲化
+
+## §1 上下文
+
+### 1.1 已有的"Gate 真相源"（review-contract.yaml）
+
+`.boll/plugins/boll-review-toolkit/contracts/review-contract.yaml` 当前 4 个 active binding：
+
+| binding | applies_when | reviewer.type | 阻塞何处 |
+|---------|-------------|---------------|----------|
+| `default-build-review` | mode=build, task_kind=code_change | pane | mode → verify |
+| `merge-ready-review` | mode=verify, transition→release | subagent (`reviewer`) | mode → release |
+| `design-review` | mode=plan, transition→build | human | mode → build |
+| `retirement-review` | operation=retire_asset | pane | retire 动作 |
+
+`verify-gate.ts` Stop hook 按 binding 校验 evidence packet → 决定 stop allow/block；`transition.ts` 按 transition_target 校验。**这是已有的 schema-level 真相源**——H5 不重建，H5 是"补字段"。
+
+### 1.2 散落的行数限额（4 个 ADR、4 处口径）
+
+| 来源 | 限额 | 适用 |
+|------|------|------|
+| ADR-H0 §H0.2 | ADR ≤300 / PLAN ≤500 | 所有 H 子计划文档 |
+| ADR-H1 INV-H1-1 + 受管资产 | lead/SKILL.md "## 触发节奏（H1）" 段 ≤30 行；全文 ≤220 | H1 嵌入段 |
+| ADR-H3 INV-H3-2 v1.1 | MEMORY.md `## ` 父段 ≤80 / `### ` 子段 ≤50 / 主索引 ≤200 | MEMORY.md |
+| ADR-H4 INV-H4-1 | lead/dev/nature-designer skill prompt 段 ≤30 行 | H4 受管 SKILL.md 段 |
+
+各 ADR 独立写、独立约束、独立验证（每个 ADR 自己的 §H0 自检表手动 wc -l），**没有 schema-level 收口**。reviewer 必须人脑读每个 ADR 才知道某文件应该限多少行，prompt-level 70% 遵从。
+
+### 1.3 已发生的 4 次"非起草人 reviewer signoff"
+
+| H | verdict 文件 | 路径形态 |
+|---|-------------|---------|
+| H2 | reviewer-verdict-20260428-1730.md | tasks/PLAN-H2/（根） |
+| H3 | reviewer-verdict-20260428-1741.md | tasks/PLAN-H3/（根） |
+| H4 | reviewer-verdict-20260428-1810.md | tasks/PLAN-H4/（根） |
+| H1 | reviewer-verdict-20260428-183611.md | tasks/PLAN-H1/WP-05/（WP 子目录） |
+
+**两个一致 + 两个不一致**：路径形态发散；reviewer subagent 类型一致（都是 `pr-review-toolkit:code-reviewer`），但 spawn 方式无 contract 约束——靠"上次怎么做这次照做"的 prompt-level 模式复用，70% 遵从。
+
+### 1.4 触发动机
+
+H 系列 PLAN §3.3 给 H5 的 DoD：**Gate 清单 ≥5 + inflation 规则 ≥3 + 跳 Gate 决策表 + 自指自检**。本 ADR 给出 H5 决策本质，不是工程节奏（节奏在 PLAN-H5）。
+
+## §2 决策本质（Decision Substance）
+
+**一句话**：把 §1.2 的行数限额和 §1.3 的执检分离从"散落 prompt + 人脑遵从"升级到 review-contract.yaml 的 `inflation` 子字段，让 verify-gate.ts 直接读 schema 判定，不再需要 reviewer 人脑遍历 ADR。
+
+**只调字（schema 字段），不加机制（不写新 hook、不写 metrics、不建 dashboard）**——继承 ADR-041 v1.0 + ADR-H4 INV-H4-3 反例表第 2/3 条。
+
+**与 H4 边界**（H 系列 plan §3.3.1 表）：
+- H4 = prompt 治理（lead/SKILL.md 行为偏好段，纯文字，prompt-level 70%）
+- H5 = Gate 量纲化（review-contract.yaml inflation 字段，纯 yaml，schema-level 100%）
+- 不交叉：H5 不动 SKILL.md prompt 段；H4 不动 review-contract.yaml
+
+## §3 INV-H5（不变量，3 条）
+
+### INV-H5-1：行数硬限 schema 化
+
+review-contract.yaml 增加 top-level `line_caps` 字段（注：不是每个 binding 重复写，而是顶层一次性定义、binding 通过 ref 引用），列出 §1.2 4 处散落的限额，**作为 verify-gate.ts 校验 evidence packet 时的可读字段**。每条 cap 字段格式：
+```yaml
+line_caps:
+  - id: adr-h-series
+    glob: "docs/decisions/ADR-H*.md"
+    max_lines: 300
+    source_adr: ADR-H0 §H0.2
+  ...
+```
+
+**红线**：
+- 修改限额数值不算 H5 工作面（数值由各原始 ADR 决定，H5 仅做收口聚合 + ref 指针）
+- 增加新 cap 项必须在原始 ADR 中先有"≤N 行"明文规定
+
+### INV-H5-2：执检分离 binding 化
+
+review-contract.yaml 的 `merge-ready-review` binding 增加 `drafter_reviewer_separation` 子字段：
+
+```yaml
+drafter_reviewer_separation:
+  required: true
+  rationale: ADR-H0 §H0.3 执检分离
+  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
+```
+
+**统一 verdict 路径形态为 `WP-05/`** —— H1 的形态（已经发生，不改 H1/2/3/4 的历史 verdict 文件位置）；新一轮起草必须遵守。
+
+**红线**：
+- 不实施"自动 spawn reviewer"逻辑（H5 仅声明 schema，spawn 仍由起草人手动触发——这是 ADR-H4 INV-H4-3 反例表第 4 条 ❌"加 SKILL.md 教 AI 自己识别推卸"的反向预防）
+
+### INV-H5-3：零机制实际引入（不只是关键词）
+
+**验证 = 实际引入检测**（不是裸 word frequency；反例声明 / 验证命令字符串自身不算违反，避免自指悖论）：
+
+1. `find docs/decisions/tasks/PLAN-H5 .boll/plugins/boll-review-toolkit -newer docs/decisions/ADR-H0-meta-charter.md -name "*.ts"` = 0（H5 工作面无新增 hook ts 文件）
+2. `git diff --stat HEAD~10..HEAD -- 'src/scripts/hooks/h5*' '.boll/plugins/*/hooks/h5*'` = empty（无 H5 命名的 hook 引入）
+3. review-contract.yaml diff 中无 `cron:` / `schedule:` / `polling_interval:` / `auto_spawn_reviewer:` 等 schema 字段
+4. ADR-H5 + PLAN-H5 § 正文（排除 §3 INV-H5-3 / §7 不做什么 / §9 H0 自检验证命令字符串）不引入机制实施动词（"创建"/"启动"/"调度"+ metrics|dashboard|hook 名词搭配）
+
+**等价于 INV-H1-3 的 H5 翻版** + **修正 INV-H1-3 朴素 grep 的自指 false positive**：把 ADR-H4 INV-H4-3 反例表升级到 schema-检查级。
+
+## §4 跳 Gate 决策表（DoD ≥5 行）
+
+| # | 场景 | 是否可跳 | 需要什么签字 | 证据落地 |
+|---|------|----------|-------------|---------|
+| 1 | binding active=false（review-contract.yaml 中显式声明非活跃） | ✅ 跳 | yaml `active: false` 即声明 | yaml diff 即证据 |
+| 2 | retirement-review 类高放射半径动作 | ❌ 不可跳 | human attestation | evidence packet kind=retire |
+| 3 | merge-ready-review 起草人 = reviewer 同体 | ❌ 不可跳 | INV-H5-2 binding 强制 | WP-05/ verdict 文件存在性 |
+| 4 | line_caps 超限 | ⚠ 条件跳 | 起草人显式 disclosure（ADR §H0 自检段写"已知超限 N 行 + 理由"）+ Nature 单签 | ADR diff 显式 disclosure 段 |
+| 5 | design-review (plan→build transition) | ❌ 永不可跳（review-contract.yaml `bypass_requires: never`） | — | yaml 即证据 |
+| 6 | hot-fix（生产 P0 issue） | ⚠ 24h 内补 reviewer signoff | Nature 口头授权 + issue 文档 | docs/issues/guard-*.md + 24h 内 reviewer-verdict-*.md |
+
+**红线**：跳 Gate ≠ 不留证据。任何跳过路径必须有可机器读的痕迹（yaml 字段 / disclosure 段 / issue 文档）——满足 ADR-H0 §H0.6 证据机械化。
+
+## §5 inflation 规则（DoD ≥3 条）
+
+### 规则 1：行数硬限优先于"先合并再清理"
+ADR-H0 §H0.2 已有，本 ADR 强化为 review-contract.yaml `inflation.no_grow_now_clean_later` 字段。任何 PR 提交 line_caps 超限 → verify-gate.ts 直接 block，不接受"merge 后下个 PR 拆"理由。
+
+### 规则 2：非起草人 reviewer 强制
+INV-H5-2 已声明 schema；本规则补充：reviewer 与起草人必须不同 session（H0.3 执检分离的实操）；`pr-review-toolkit:code-reviewer` subagent 自身就是不同 session，物理满足。
+
+### 规则 3：自指自检段必填
+任何 ADR-Hx 必须包含 `## §H0 自检` 段，列出 H0.1-H0.6 + H0.meta 7 条逐条勾选状态——本 ADR §10 即为示范。verify-gate.ts 通过 grep `^## .*H0 自检` 校验存在性。
+
+## §6 H4 vs H5 边界（再次强调）
+
+| 关注点 | H4（已闭合） | H5（本 ADR） |
+|--------|-------------|-------------|
+| 改的文件 | lead/SKILL.md（prompt） | review-contract.yaml（schema） |
+| 治什么 | 行为偏好（黑话/推卸/过度 review） | 节奏/限速/执检分离 |
+| 遵从层级 | prompt-level 70% | schema-level 100% |
+| 哲学 | 调字不加机制 | 调字（yaml 是"字"）不加机制 |
+
+H5 不撤销 H4，也不重写 H4 的 prompt 段。两者并行生效。
+
+## §7 不做什么（边界声明）
+
+- ❌ 不写新 hook（INV-H5-3 红线）
+- ❌ 不在 verify-gate.ts 加新逻辑（仅靠 yaml schema 字段读取，原有 contract-driven 框架已够用；如果某字段需要解释，由后续单独 ADR 决定）
+- ❌ 不动 H4 的 SKILL.md prompt 段
+- ❌ 不动 H1 的"## 来自 crystal-learn 的门禁"接收段
+- ❌ 不引入 metrics/dashboard（INV-H5-3）
+- ❌ 不"自动 spawn reviewer"——人手起 subagent 仍是当前模式（70% 遵从足够；schema 级别只规范"必须发生"和"形态"，不规范"如何触发"）
+
+## §8 受管资产（scope 锁死）
+
+| # | 路径 | 动作 | 限额 |
+|---|------|------|------|
+| 1 | `.boll/plugins/boll-review-toolkit/contracts/review-contract.yaml` | 增加 `line_caps` 顶层字段 + 在 `merge-ready-review` binding 增加 `drafter_reviewer_separation` 子字段 + `inflation` 顶层字段 | 当前 132 行 → 目标 ≤220 行 |
+| 2 | `docs/decisions/ADR-H5-gate-quantization.md` | 本 ADR | ≤300 行 |
+| 3 | `docs/decisions/PLAN-H5-gate-quantization.md` | 工程计划 | ≤500 行 |
+| 4 | `docs/decisions/tasks/PLAN-H5/WP-04/dogfood-output-*.md` | dogfood 产出 | ≤80 行 |
+| 5 | `docs/decisions/tasks/PLAN-H5/WP-05/reviewer-verdict-*.md` | reviewer signoff | 由 reviewer 决定 |
+
+**禁动**：
+- `.boll/skills/lead/SKILL.md`（H4 受管）
+- `~/.boll/skills/boll-crystal-learn/SKILL.md`（H1 受管）
+- `~/.boll/projects/-Users-nature------boll/memory/MEMORY.md`（H3 受管）
+- 任何 hook 文件（INV-H5-3）
+
+## §9 H0 自检（H0.1-H0.6 + H0.meta）
+
+| 条款 | 内容 | 本 ADR 状态 |
+|------|------|-------------|
+| H0.1 施工隔离 | scope 显式列出 | ✅ §8 受管资产表 + frontmatter applies_scope |
+| H0.2 节流限速 | ADR ≤300 行 | ✅ 终稿 wc -l 验（estimated 200-220） |
+| H0.3 执检分离 | 起草人 ≠ 签字人 | ✅ WP-05 reviewer subagent 独立 |
+| H0.4 自指禁止 | 不重现要修的症状 | ✅ INV-H5-3 + §7 反例表是 ADR-H4 INV-H4-3 第 2/3 条的本 H 翻版，物理避免 |
+| H0.5 跨 H 协调 | 共改文件冲突表 | ✅ §6 H4/H5 边界表；review-contract.yaml 仅本 H 改动 |
+| H0.6 证据机械化 | DoD 证据机器可生成 | ✅ §4 跳 Gate 表 + §5 规则均给 grep/yaml field 校验路径 |
+| H0.meta | 不引未来 H | ✅ grep `H[6-9]` = 0（H9 已存在不算未来；下方 grep 验证） |
+
+H0.meta 验证命令（排除 code block，避免命令字符串自指 false positive）：
+```bash
+awk '/^```/{f=!f; next} !f' docs/decisions/ADR-H5-gate-quantization.md | grep -cE "\bH[6-8]\b"
+# 应为 0（H6/H7/H8 是未来 H；排除 code block 后命令字符串自身不算引用）
+```
+
+## §10 dogfood 规划
+
+H5 自身走一次 Gate 即 PLAN-H5 WP-04：
+- 起草本 ADR-H5 + PLAN-H5 时，本身要满足 INV-H5-1（行数）+ INV-H5-3（无机制关键词）
+- WP-04 dogfood-output-*.md 记录"H5 起草过程触发了哪些 line_caps 边界"
+- WP-05 reviewer signoff 验证"H5 自己是否被 H5 的规则约束住"——典型 ADR-038 D11.2 实例
+
+## §11 与现行 vNext 共存
+
+- review-contract.yaml 修改前必须 `git diff` 验证：4 active binding 未被破坏
+- 修改后跑 `verify-gate.ts` 一次手动测试（PLAN-H5 WP-03 DoD）
+- 如发现 verify-gate.ts 因新字段崩溃 → 回退 yaml + ADR-H5 重新设计字段位置（H 系列 plan §3.3.4 中等回退）

package/src/bollharness/docs/decisions/ADR-H6-state-file-health.md

@@ -0,0 +1,211 @@
+---
+adr: ADR-H6
+title: 状态文件健康度（state 清单 schema 化 + 健康度指标 + stale 清理 + 抗 compact 接口签字）
+status: accepted
+date: 2026-04-28
+parent_charter: ADR-H0-meta-charter.md
+philosophy_inheritance:
+  - ADR-041-codex-integration v1.0（"调字不加机制"）
+  - ADR-H4 INV-H4-3 反例表（不写 metrics / 不写 dashboard / 不写 hook 治节奏）
+  - ADR-H5 INV-H5-3（实际引入检测取代裸 grep；awk 排除 code block 自指悖论修正）
+  - ADR-038 D11.2（schema-level 100% > prompt-level 70%）
+applies_scope:
+  - .boll/plugins/boll-review-toolkit/contracts/review-contract.yaml（增 state_inventory + state_health_indicators 顶层字段）
+  - .boll/state/_archived/（新建：归档目录）
+  - .boll/state/.DS_Store（删除）
+  - .boll/state/completion-proposal-profile-build-cli-archived-20260419-1110.json（移到 _archived/）
+  - .boll/state/harness-review-2026-04-14/（移到 _archived/）
+  - 本 ADR 自身（自指 dogfood）
+not_in_scope:
+  - .boll/state/round{1-5}-verdicts/（审计依据，原地保留不动）
+  - .boll/proposals/（self-evolution 足迹，只增不删）
+  - .boll/guard/（once-flag/loop-counter 活工具态，#4 认知修正）
+  - .boll/inbox/（H9 受管，不动）
+  - .boll/evidence/（各 PLAN 受管，不动）
+  - 任何新 hook（INV-H6-3 红线）
+  - ADR-042 D3/D4 写屏障逻辑（仅引用，不改）
+---
+
+# ADR-H6：状态文件健康度
+
+## §1 上下文
+
+### 1.1 .boll/ 现状盘点（实测 2026-04-28T19:12）
+
+| 路径 | 当前状态 | 健康度判定 |
+|------|---------|-----------|
+| `.boll/state/mode` | 6 字节 | ✅ 动态运行期 |
+| `.boll/state/run.json` | 3 字节 | ✅ 动态运行期 |
+| `.boll/state/locks.json` | 3 字节 | ✅ 动态运行期 |
+| `.boll/state/completion-proposal.json` | 6048 字节 / Apr 19 | ✅ 当前 run 提案 |
+| `.boll/state/risk-snapshot.json` | 877 字节 / 实测 mtime 当下 | ✅ 由 risk-tracker 实时维护 |
+| `.boll/state/round{1-5}-verdicts/` | 5 个目录 / Apr 16-19 | ✅ 审计归档保留 |
+| `.boll/state/harness-review-2026-04-14/` | 目录 / Apr 14 | ⚠ 14 天前归档，应移 _archived/ |
+| `.boll/state/completion-proposal-profile-build-cli-archived-20260419-1110.json` | 4737 字节 / Apr 19 | ⚠ 文件名已含 archived 但在主目录 |
+| `.boll/state/.DS_Store` | 6148 字节 / Apr 16 | ❌ macOS 噪声 |
+| `.boll/proposals/` | 265 文件 | ✅ self-evolution 痕迹（只增不删） |
+| `.boll/guard/` | 11321 文件 | ✅ once-flag/loop-counter 活工具态（#4 认知修正） |
+| `.boll/log/harness-self-symptoms.md` | 1 文件 | ✅ H 系列自指审计 |
+| `.boll/log/hook/` | 目录 | ✅ hook ledger |
+| `.boll/inbox/**` | H9 受管 | ✅ 不动 |
+| `.boll/evidence/**` | 各 PLAN 受管 | ✅ 不动 |
+
+### 1.2 触发动机
+
+H 系列 plan §3.3 给 H6 的 DoD：**state 清单 ≥10 + 健康度指标 ≥3 + ADR-042 D9 接口签字 + 3 stale 清理**。本 ADR 给出 H6 决策本质，不是工程节奏（节奏在 PLAN-H6）。
+
+### 1.3 与 H5 的协同关系
+
+H5 已经在 review-contract.yaml 增加了 `line_caps` + `inflation` + `drafter_reviewer_separation` 三处 schema 字段（commit `872f03ce`）。H6 直接复用同一 yaml 作为 schema 真相源，增加 `state_inventory` + `state_health_indicators` 两处顶层字段——**不再分散到独立 yaml/json**。
+
+## §2 决策本质
+
+**一句话**：把 §1.1 现状清单和"什么算 state 健康"从"散落在 ADR-038/ADR-042/各 plan §6"升级到 review-contract.yaml 顶层 `state_inventory` + `state_health_indicators` 字段——schema-level 真相源。同步把 3 个明确 stale 文件（.DS_Store + archived JSON + Apr 14 review）物理移走或删除。
+
+**只调字（schema 字段 + 文件移动），不加机制**——继承 ADR-041 v1.0 + ADR-H4 INV-H4-3 反例表 + ADR-H5 INV-H5-3 实际引入检测原则。
+
+**抗 compact 接口签字**：本 ADR §6 显式签字"抗 compact 真相源 = ADR-042 D3 (Session-Owner ownership.yaml) + D4 (owner-guard.ts) 写屏障"；H6 不重做、不另建。AGENTS.md 渐进加载（ADR-042 D9）作为 Codex 抗 compact 路径同样签字接受。
+
+## §3 INV-H6（不变量，3 条）
+
+### INV-H6-1：state 清单 schema 化
+
+review-contract.yaml 增加顶层 `state_inventory` 字段，列出 §1.1 表的全部 ≥10 条 state 资产（按 dynamic / archived / append-only / managed-by-other-H 四类标注）。
+
+```yaml
+state_inventory:
+  - id: state-mode
+    path: ".boll/state/mode"
+    kind: dynamic
+    owner: boll-mode-toolkit
+  ...
+```
+
+**红线**：增加新 state 资产必须在原始 ADR（ADR-038 / ADR-042 / ADR-Hx）中先有声明；H6 不发明新 state。
+
+### INV-H6-2：state 健康度指标 schema 化
+
+review-contract.yaml 增加顶层 `state_health_indicators` 字段，定义 ≥3 条机器可读指标：
+
+```yaml
+state_health_indicators:
+  - id: schema-validity
+    desc: "5 个 dynamic JSON 文件 (mode/run.json/locks.json/completion-proposal.json/risk-snapshot.json) JSON parse 通过 + 必填字段非空"
+    check: "npx ts-node -e 'import json; for p in [...]: json.load(open(p))'"
+  - 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 == 0（顶层）"
+  - id: inbox-unread-volume
+    desc: ".boll/inbox/main/unread/ ≤50 文件（H9 ADR 红线复用）"
+    check: "ls .boll/inbox/main/unread/ | wc -l ≤ 50"
+```
+
+**红线**：指标必须 schema-level 可验证（机器可读 check 命令）；不引入"AI 自我评估"或"主观 health score"。
+
+### INV-H6-3：零机制实际引入（继承 INV-H5-3 修正版）
+
+验证 = 实际引入检测（不是裸 word frequency；反例段豁免，避免 INV-H1-3 自指悖论）：
+
+1. `find .boll/state/_archived .boll/plugins/boll-review-toolkit -newer docs/decisions/ADR-H0-meta-charter.md -name "*.ts"` = 0
+2. `git diff HEAD~5..HEAD --stat -- 'src/scripts/hooks/h6*' '.boll/plugins/*/hooks/h6*'` = empty
+3. review-contract.yaml diff 中无 `cron:` / `schedule:` / `polling_interval:` / `auto_*:` 等触发字段
+4. ADR-H6 + PLAN-H6 § 正文（排除 §3 INV-H6-3 / §7 不做什么 / §9 H0 自检）不引入机制实施动词搭配，搭配定义见以下 fence：
+
+```text
+verbs = (创建|启动|调度)
+mechanism_nouns = (metrics|dashboard|hook)
+violation = verbs.*mechanism_nouns
+```
+
+## §4 stale 清理决策表（DoD 3 stale）
+
+| # | 路径 | 大小 / mtime | 决策 | 理由 |
+|---|------|-------------|------|------|
+| 1 | `.boll/state/.DS_Store` | 6148 / Apr 16 | **物理删除** + 加 `.gitignore` | macOS 噪声，无信息价值；防止再生 |
+| 2 | `.boll/state/completion-proposal-profile-build-cli-archived-20260419-1110.json` | 4737 / Apr 19 | **移到 `.boll/state/_archived/`** | 文件名已含 archived 标识，应物理位置匹配 |
+| 3 | `.boll/state/harness-review-2026-04-14/` | 目录 / Apr 14 | **移到 `.boll/state/_archived/`** | 14 天前归档；移走后 `.boll/state/` 顶层只剩 dynamic + round{1-5}-verdicts/（仍是审计依据，保留） |
+
+**禁动**：
+- `.boll/state/round{1-5}-verdicts/` —— 审计依据，原地保留
+- `.boll/proposals/` —— self-evolution 足迹，只增不删
+- `.boll/guard/` —— 11321 文件按 #4 认知修正是活工具态（once-flag/loop-counter）
+
+## §5 跳 Gate 决策表（继承 ADR-H5 §4，不重写）
+
+H6 涉及的 Gate 由 ADR-H5 §4 跳 Gate 决策表统一治理。本 ADR 不重复定义跳 Gate 表；引用：
+- merge-ready-review binding（含 INV-H5-2 drafter_reviewer_separation）
+- line_caps 中本 ADR + PLAN-H6 受 adr-h-series ≤300 / plan-h-series ≤500 限制
+
+## §6 抗 compact 接口签字（plan §3.3 H6 DoD：ADR-042 D9 接口签字）
+
+H6 显式签字接受以下抗 compact 真相源，不重做、不另建：
+
+| 抗 compact 路径 | 真相源 | 签字状态 |
+|----------------|--------|---------|
+| AI 自识 "我是谁、own 什么" | ADR-042 D3 Session-Owner 真相源 + ownership.yaml + AI 自识协议 | ✅ H6 签字接受 |
+| 写权限物理隔离 | ADR-042 D4 owner-guard.ts PreToolUse 写屏障 hook | ✅ H6 签字接受（hook 已存在，H6 不动其代码） |
+| Codex 渐进加载 | ADR-042 D9 AGENTS.md 渐进加载体系 | ✅ H6 签字接受 |
+| H 系列窗口邮箱 cross-session 通信 | ADR-H9 inbox 路径约定 + SessionStart 注入 | ✅ H6 签字接受（H9 受管，不动） |
+| state 文件 fresh-load | review-contract.yaml `state_inventory` + 各 owner skill SessionStart 重读 | ✅ H6 提供 schema 真相源 |
+
+**红线**：H6 不重新设计抗 compact 协议；H6 仅做"清单 + 健康度 + 签字接受"。
+
+## §7 不做什么（边界声明）
+
+- ❌ 不写新 hook（INV-H6-3 红线）
+- ❌ 不在 verify-gate.ts 加新逻辑（schema 字段先存在，消费链路留 H 系列收尾后单独 ADR）
+- ❌ 不动 .boll/proposals/（self-evolution 足迹）
+- ❌ 不动 .boll/guard/（活工具态）
+- ❌ 不动 .boll/inbox/（H9 受管）
+- ❌ 不动 .boll/evidence/（各 PLAN 受管）
+- ❌ 不重做 ADR-042 D3/D4/D9 抗 compact 协议
+- ❌ 不引入 metrics/dashboard/AI 自评估 health score（INV-H6-3）
+- ❌ 不动 .boll/state/round{1-5}-verdicts/（审计依据）
+
+## §8 受管资产（scope 锁死）
+
+| # | 路径 | 动作 | 限额 |
+|---|------|------|------|
+| 1 | `.boll/plugins/boll-review-toolkit/contracts/review-contract.yaml` | 增 `state_inventory` + `state_health_indicators` 顶层字段 | ≤300 行（H5 后 171 → 目标 ≤270） |
+| 2 | `docs/decisions/ADR-H6-state-file-health.md` | 本 ADR | ≤300 行 |
+| 3 | `docs/decisions/PLAN-H6-state-file-health.md` | 工程计划 | ≤500 行 |
+| 4 | `docs/decisions/tasks/PLAN-H6/WP-04/dogfood-output-*.md` | dogfood 产出 | ≤80 行 |
+| 5 | `docs/decisions/tasks/PLAN-H6/WP-05/reviewer-verdict-*.md` | reviewer signoff | reviewer 决定 |
+| 6 | `.boll/state/_archived/` | 新建目录 | — |
+| 7 | `.gitignore` | 加 `.boll/state/.DS_Store` 规则 | — |
+| 8 | `.boll/state/.DS_Store` | 删除 | — |
+| 9 | `.boll/state/completion-proposal-profile-build-cli-archived-20260419-1110.json` | git mv → `_archived/` | — |
+| 10 | `.boll/state/harness-review-2026-04-14/` | git mv → `_archived/` | — |
+
+## §9 H0 自检
+
+| 条款 | 内容 | 状态 |
+|------|------|------|
+| H0.1 施工隔离 | scope 显式列出 | ✅ §8 + frontmatter applies_scope/not_in_scope |
+| H0.2 节流限速 | ADR ≤300 行 | 待终稿 wc -l 验证（estimated 230-260） |
+| H0.3 执检分离 | 起草人 ≠ 签字人 | ✅ WP-05 reviewer subagent 独立 |
+| H0.4 自指禁止 | 不重现要修的症状 | ✅ INV-H6-3 继承 H5 修正版；不重现"自指 false positive" |
+| H0.5 跨 H 协调 | 共改文件冲突表 | ✅ §7 不做什么 + §3 跨 H 协调（H6 仅改 review-contract.yaml + state/，不撞其他 H） |
+| H0.6 证据机械化 | DoD 证据机器可生成 | ✅ §3 INV + §4 stale 表 + §6 抗 compact 表均给 grep/find/yaml field 校验 |
+| H0.meta | 不引未来 H | ✅（H8 已存在不算未来；下方 grep 验证） |
+
+H0.meta 验证命令（继承 H5 awk 排除 code block 模板）：
+```bash
+awk '/^```/{f=!f; next} !f' docs/decisions/ADR-H6-state-file-health.md | grep -cE "\bH(7|10|11|12)\b"
+# 应为 0（H7 退役不算未来；H10+ 是未来 H）
+```
+
+## §10 dogfood 规划
+
+PLAN-H6 WP-04 用 H6 起草过程自身做输入：
+- ADR-H6 + PLAN-H6 + review-contract.yaml diff 满足 INV-H6-3 4 项检测
+- 3 stale 清理动作的 git mv / git rm 物理结果可机器验证
+- WP-04 输出文件 ≤80 行，自身受 INV-H6-1 line-cap 约束
+
+## §11 与现行 vNext 共存
+
+按 H 系列 plan §3.3.3：
+- review-contract.yaml 修改后跑 yaml.safe_load 验证（PLAN-H6 WP-03 DoD）
+- 4 active binding + H5 三字段（line_caps / inflation / drafter_reviewer_separation）不动
+- `.boll/state/_archived/` 新建对 verify-gate.ts / transition.ts / capability-router.ts 透明（不会影响 mode/run.json/locks.json 读取路径）
+- 3 stale 文件移动用 `git mv`（保留历史）+ git rm（仅 .DS_Store）