verification.html §3.4 REQ-VER-004 は golden baseline の 2-dir model (baselines/reference/ = VCS golden vs baselines/local/ = 実行生成) と明示的 accept workflow (例 runner.sh --accept) を規定済だったが、 CLI subcommand 検証の具体的 harness は未実装だった。
Track 1 (folio inventory、 REQ-VER-010) 着手時、 既存 scratch/verification/runner.sh は hook 専用 (mock payload を .claude-plugin/scripts/check-<name>.sh に pipe → exit_code + stderr assert) であり、 file を生成する CLI subcommand を検証できないことが判明した。 CLI 検証の harness 設計 (assertion 方式・runner 構造・非決定性の扱い) を確定する必要があった。 user は golden-diff 方式 (e2e 目視でなく byte-exact 比較) を選択した。
scenario YAML に kind field を導入する (verification.html §3.2): hook (既定、 省略可、 従来の payload 検証) と cli-golden (CLI subcommand を golden 比較)。
kind: cli-golden の scenario に対し harness は: (1) bin/folio を scenario の command で repo root 実行 (output_file 生成)、 (2) output_file を baselines/local/ に materialize、 (3) output_file と golden を jq -S + normalize.exclude_paths 削除で正規化、 (4) 正規化 JSON の byte-exact 一致 + exit_code 一致を assert。 --accept で baselines/local/ → baselines/reference/ へ golden を promote (REQ-VER-004 accept workflow、 raw 保持)。
golden には generatedAt 等の非決定的 field を raw のまま保持する (relations.html §4.1 で MUST)。 比較時のみ normalize.exclude_paths (jq path、 例 [".generatedAt"]) で除外し、 byte-exact 比較を決定的にする。
新規 runner-cli.sh を設けず、 既存 runner.sh を拡張する。 kind // "hook" を early-dispatch し、 cli-golden のみ専用 handler へ分岐、 hook flow は 1 行も変えない (regression 防止)。 invocation は ./runner.sh [--accept] scenarios/X.yaml で統一する。
baselines/{reference,local}/ + --accept をそのまま実装--accept / merge 時に golden を人間が精査 (Track 1 で 13 entries 精査済)normalize.exclude_paths の保守が必要jq 依存 (既存 runner と同じ前提のため新規依存ではない)| 案 | 採用しなかった理由 |
|---|---|
| 案 A (採用): golden-diff harness = runner.sh 拡張 + kind:cli-golden | byte-exact・決定的・CI 可能、 既存 2-dir 基盤 (REQ-VER-004) 再利用、 単一 entry point |
案 B: 別 script runner-cli.sh 新設 | entry point が 2 つに分裂、 invocation 分岐、 yq/jq setup 重複 |
| 案 C: e2e 目視観察のみ (agent eyeball、 REQ-VER-009 型) | byte-exact でなく構造化出力に CI 決定性なし。 user が golden-diff を選択 (検証の厳密性重視) |
| 案 D: exit code のみ assertion (REQ-VER-003 hook model) | CLI は構造化 file を出力、 exit code だけでは内容を検証できない |
| 案 E: JSON Schema validation (ajv) を golden の代わりに | 試作には golden-diff が単純で regression 捕捉に十分。 schema validation は完成形の追加層 |
scratch/verification/runner.sh (kind:cli-golden handler、 commit c65a2de = Track 1)folio inventory、 scenario inventory-gen.yaml)