ADR-0017 — verification の unit (sandbox) vs integration (e2e) 境界

§1. Context

ADR-0013 は sandbox verification framework (scratch/verification/) の存在を決定したが、 framework 内部に 2 種の検証 method が育った後も両者の境界は明文化されていなかった:

sandbox 単体テスト (scenarios/ + runner.sh): hook script 単体を mock JSON payload で発火 (echo | bash、 REQ-VER-003 = exit code 中心)、または CLI subcommand 単体を golden-diff (ADR-0018 kind:cli-golden)。 plugin load 非依存・決定的・CI 可能。
e2e 統合テスト (e2e/ + runbook.md): live load 済 plugin をひとまとまりの道具として実 Edit/Write tool 操作 + fresh session 起動で発火させる (REQ-VER-009)。一次 assertion は file 作成有無。

Track 1 (cli-golden、 ADR-0018) と Track 2 (ADR-0007 context injection の e2e S-F) でこの 2 method が両方とも実体を持ったため、 verification.html §5.2 が「Phase X3 Step 1 完了後」に予約していた本 ADR (hook unit test vs integration test 境界) を起票確定する時期に達した。確定すべきは: どの failure class をどちらの層が所有するか、 各層の assertion model、 integration 層でしか検証できない behavior の判定規則。

§2. Decision

§2.1 二層モデルを採用する

folio の verification は unit 層 (sandbox) と integration 層 (e2e) の 2 層で構成する。両者は包含関係になく、 所有する failure class が異なる 相補的な層である。

軸	unit 層 (sandbox)	integration 層 (e2e)
location	`verification/scenarios/` + `runner.sh`	`verification/e2e/` + `runbook.md`
検証対象	hook script 単体 / CLI subcommand 単体 (隔離)	live load 済 plugin 全体 (hook chain + marker + SKILL + SessionStart)
発火	mock payload `echo \| bash` (kind:hook) / `bin/folio` 直接実行 (kind:cli-golden)	実 Edit/Write tool 操作 + fresh session 起動 (agent-driven)
assertion	exit code + stderr_contains (REQ-VER-003) / byte-exact golden-diff (ADR-0018)	file 作成有無 (deny→不在 / notify→存在、 REQ-VER-009) + fresh session の context 観察 (S-F)
実行者 / 決定性	`runner.sh` (自動・決定的・CI 可能・plugin load 非依存)	agent が runbook を walk (live plugin load 必須・CI 不可)
所有 failure class	hook / CLI のロジック正当性 (component 単位)	plugin packaging・hook 登録・hook 間相互作用・Claude Code 統合点 (deny bug 可視性・SessionStart source 発火・stdout→context 注入)

§2.2 unit 層が既定 (default to unit)

ある behavior が 単一 script への mock payload または 単一 CLI command の隔離実行で exercise できるなら、その behavior は unit 層で検証する MUST。 unit 層は決定的・高速・CI 可能であり、 regression を component 単位で pinpoint できる。 integration 層は unit で代替できない場合の例外として用いる (e2e は実 session / 実 tool / agent walk が必要でコスト大)。

§2.3 integration 層でしか検証できない behavior (integration-only)

以下は mock が再現できない live Claude Code runtime 依存であり、 unit 層に移せない。これらは integration 層 (e2e) で検証する MUST:

実 tool 発火: hook が実際の Edit/Write tool 呼び出しで発火するか (mock payload は「script が動く」ことしか示さない)。加えて PreToolUse deny の可視性問題 (research §2.6 / Issue #39344) のため一次 assertion を file 作成有無に置く。
hook 間相互作用: 複数 hook (caller-marker + path-boundary 等) の実行順序・1 つが deny した時の他 hook 挙動。
SessionStart source 発火 + stdout→context 注入: SessionStart が startup / compact 等の source で実際に発火し、その stdout が agent context に注入されるか。これは Claude Code の SessionStart 機構そのものに依存する。
plugin packaging / 登録: ~/.claude/plugins/<name> symlink + cld auto discovery 経由で plugin が load され hook が登録されるか。

§2.4 規範例 — context injection (unit-testable な半分と integration-only な半分)

同一機能が unit 層と integration 層に分割される ことを最も明瞭に示すのが ADR-0007 の context injection である。この境界規則の canonical example として保持する:

digest 内容 (unit): folio prime が出力する Tier 1 digest text は kind:cli-golden + capture:stdout で golden-diff 検証する (prime-digest.yaml、 REQ-VER-012)。決定的・CI 可能。
注入そのもの (integration-only): SessionStart hook が実際に発火し stdout が context に届くかは §2.3-(3) の通り live runtime 依存で unit 化不能。 e2e で 2 source を実証: startup source = fresh spawn 観察で PASS (runbook S-F)、 compact source = 2026-05-25 の実 compaction で SessionStart:compact が Tier 1 digest を注入することを実観察 PASS (observations-sessionstart.json)。

inject-inventory.sh に mock payload を流せば「script が動く」ことは unit で言えるが、「Claude Code が stdout を context に注入する」ことは言えない — これが本 ADR の境界そのものである。

§3. Consequences

Positive

検証層の責務が明確: 新 hook / CLI は既定で unit、 §2.3 該当時のみ e2e を追加 — どちらを書くべきか迷わない
CI 健全性の基準が固定: unit 層 (sandbox + cli-golden) は plugin load 非依存で常時 green を保てる (現 6 scenario)。 e2e は live session でのみ意味を持つ補完
integration failure を取り逃さない: deny 可視性・SessionStart 注入・hook 間相互作用は unit では原理的に検出不能 → e2e で網羅する設計が明文化された
context injection 機能の完全検証: unit (digest golden) + e2e (startup + compact 両 source) で機能の両半分を被覆。 folio signature 機能がライブ実証済

Negative

e2e は CI 不可・agent walk 必須でコストが高い → §2.2 で「unit 既定・e2e 例外」を MUST 化して濫用を防ぐ
e2e の compact source 観察は実 compaction trigger が要る (再現に手間)。一度の実証で docs-canonical を補強する運用

Neutral

本 ADR は folio 内部の unit/integration 境界。 folio-sandbox 全体 vs twill experiment-verified の外部境界は ADR-0015 が担う (直交)
完成形では e2e の一部を Claude Code SDK / headless harness で半自動化する余地 (現試作は agent-driven runbook)

§4. Alternatives Considered

案	採用しなかった理由
案 A (採用): 二層モデル (unit=sandbox / integration=e2e) + 境界規則 (unit 既定、 §2.3 該当のみ e2e)	所有 failure class が相補的で包含関係なし。 unit の CI 決定性と e2e の統合被覆を両立、判定規則が明確
案 B: unit 層のみ (sandbox + cli-golden、 e2e 廃止)	deny 可視性 (research §2.6)・SessionStart 注入・hook 間相互作用が原理的に検出不能。 framework を生んだ動機 (実機統合の不確実性) を defeat
案 C: e2e 層のみ (agent eyeball で全検証)	CI 不可・非決定的・低速、 component 単位の regression pinpoint 不能。 ADR-0018 が既に golden-diff の決定性を選択済
案 D: ADR-0013 に統合 (別 ADR 化しない)	ADR-0013 は framework の存在決定。 unit/integration 境界 + 層別 assertion model は Track 1/2 で実体化した別の決定であり、 §5.2 が ADR-0017 枠を予約済
案 E: kind:hook と kind:cli-golden を別「層」と扱う	両者は共に unit 層 (隔離 component 検証)。本質的な軸は assertion 方式でなく unit-vs-integration (live runtime 依存か否か)

§5. Trace

unit 層実装: scenarios/ (kind:hook 4 + kind:cli-golden 2) + runner.sh (commit c65a2de で cli-golden 拡張)
integration 層実装: e2e/ (runbook S-A〜S-F) + golden baselines/reference/
enforce する REQ: REQ-VER-003 (unit = exit code 中心) + REQ-VER-009 (integration = e2e、 file 作成有無) + REQ-VER-012 (prime digest = unit golden、注入 = integration)
canonical example のライブ証跡: observations-sessionstart.json (S-F startup PASS + compact-source PASS、 2026-05-25)。 ADR-0007 §2.1/§3/§4 を compact-source の docs-canonical → e2e-verified に同 commit で格上げ
関連 ADR: ADR-0013 (framework 存在)、 ADR-0018 (unit の CLI 拡張)、 ADR-0007 (canonical example の機能)、 ADR-0015 (外部境界、直交)
関連 constitution 原則: P-3 (WHAT-only、本 ADR は検証層設計の why)、 P-11 (HOW 隔離、 runner / e2e は scratch/verification/)
本 ADR は verification.html §5.2 の「ADR-0017 hook unit test vs integration test 境界」 (Phase X3 Step 1 完了後) を起票確定する (retrospective、 Track 1/2 で 2 層が実体化した後)