ADR-0013 — sandbox verification framework (scratch/verification/)

Status: accepted · Date: 2026-05-23 · folio v0.4.2-draft

§1. Context

ADR-0003 で確定した Phase X3 minimal plugin (1 skill + 4 hook + 6 script + 1 CLI) を実装する前に、 「机上設計と現実の乖離」 リスクを潰す必要がある。 既存 research 2 件 (plugin-architecture-research.html / spec-graph-management-research.html) は web 上の情報のみで実機検証なし。 Claude Code 公式 hook の permissionDecision: "deny" Bug 群 (Issue #37210 / #33106 / #39344 / #18312、 すべて Closed / not planned) や hooks 数 29 種等の実挙動を自前で確認していない状態で実装に進むのは危険。

5 並列 researcher × 87 ソース調査 (plugin-sandbox-verification-research.html) で類似 plugin ecosystem (VS Code / Neovim / JetBrains / MCP Inspector / mcp-recorder / MCPSpec / Continue.dev / Aider) の test harness と AI agent eval framework (Inspect AI / Promptfoo / Hypothesis / EARS→Gherkin) を精査、 folio 用 sandbox verification framework の設計を導出した。

§2. Decision

§2.1 framework 採用

folio Phase X3 着手前に sandbox verification framework を導入する。 配置は scratch/verification/ (本体 spec とは分離、 P-11 整合)。 framework の仕様 (scope / scenario format / use case mapping / implementation phase) を scratch/specs/verification.html に集約 SSoT 化する。

§2.2 framework 構造

scratch/
├── specs/verification.html         (spec SSoT、 normative)
└── verification/                   (実体、 試作実装)
    ├── README.html                 entry + 全 scenario 一覧
    ├── scenarios/                  use case 別 YAML scenario
    ├── fixtures/                   テストデータ
    ├── baselines/
    │   ├── reference/              VCS 管理 (golden、 TypeScript 2-dir model)
    │   └── local/                  実行生成 (.gitignore)
    └── runner.sh                   軽量 bash runner

§2.3 scenario format = YAML、 1 REQ = 1 scenario

YAML を採用 (MCPSpec / Promptfoo / pytest-regressions 流)。 各 scenario は EARS REQ から Gherkin Given/When/Then に 1:1 変換 (conductofcode.io / RequireKit pattern)。 schema 詳細は verification.html §3 EARS Requirements。

§2.4 assertion 戦略 = exit code + stderr 中心

Claude Code permissionDecision: "deny" JSON は Issue #37210 / #33106 / #39344 等で動作不安定 (Closed/not planned)。 verification scenario の assertion は exit_code: 2 + stderr_contains を確実な fallback として採用する。 ADR-0016 候補で詳細規範化予定。

§2.5 runner = 軽量試作 runner

Phase X3 試作段階は軽量試作 runner (runner.sh 仮称) を採用 (試作駆動と整合、 重量 framework 導入を回避)。 完成形 (Phase X4+) では Inspect AI / Promptfoo 統合候補。 具体的な runner interface (YAML parse 方式 / 言語選定 / assertion 評価 logic / exit code 集計) は WHAT 規定外 (HOW として binding に隔離、 P-11 整合)、 Phase X3 着手時に research §10.1 Gap 2 解決後に確定する。

§2.6 3 段階 implementation phase

verification を 3 段階で導入する意思決定 (本 ADR の Decision 部分): Step 1 = hook script unit test (Phase X3 最初 MUST)、 Step 2 = worktree-based integration (中盤 SHOULD)、 Step 3 = container-based isolation (Phase X4+ MAY)。 detailed table (方式 / API call / 適用 Phase) は verification.html §4.1 を SSoT として参照する MUST (DRY 整合、 本 ADR は意思決定 trace のみ)。

§3. Consequences

Positive

Negative

Neutral

§4. Alternatives Considered

案採用しなかった理由
案 A: 公式 Claude Code sandbox 待ちBoxLite sandbox 統合提案 (Issue #15888) は Anthropic "not planned" で却下済。 公式 plugin isolation sandbox は存在しない
案 B: twill experiment-verified 方式 (情報単位)P-3 WHAT-only / P-11 HOW 禁止と衝突。 詳細は ADR-0015
案 C: Inspect AI / Promptfoo を最初から採用試作段階で重量、 Python / Node 依存導入、 hook script 中心の folio に過剰。 Phase X4+ 候補として保留
案 D: verification framework なしで実装着手「机上設計と現実の乖離」 リスク (permissionDecision deny bug 等) を放置、 試作後の修正 cost 爆発

§5. Trace