evidence-ledger

name	evidence-ledger
description	完了主張を証拠付きで記録し、EvidenceLedger を出力する。Use when: 「完了した」「修正した」「テストが通った」と言う前に証拠を記録したい時。/pg verify の出力先として使用。「証拠を残したい」「完了判定をしたい」「TDD証跡を残したい」「Completion Gateに渡したい」。

Evidence Ledger

完了主張を証拠付きで記録し、EvidenceLedger として出力する。

Iron Law

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

「should work now」「probably fixed」「テスト通るはず」等の推測的完了宣言は禁止。 コマンド実行結果・終了コード・出力抜粋を証拠として記録せよ。

TDD 必須 mode では、単なる「テストが通った」だけでは不十分。 RED（期待通り失敗）→ GREEN（最小実装で成功）→ REFACTOR VERIFY（整理後も成功） の証跡を分けて記録する。

Common Rationalizations

こう思ったら	現実
「CIが通ったから証拠不要」	CI はカバレッジの保証ではない。claim ごとに証拠を記録せよ
「小さな修正だから証拠不要」	規模は関係ない。exitCode=0 を確認して記録せよ
「レビューしたから大丈夫」	review type の EvidenceItem として記録せよ
「テストが通ったからTDD済み」	GREENだけではTDD証跡にならない。REDの失敗理由も記録せよ
「REDは見たがログは残していない」	high-risk / critical では RED 証跡がなければ Completion Gate で block 対象

データスキーマ

EvidenceStatus

"passed" | "failed" | "skipped" | "unknown"

EvidenceType

"command" | "diff" | "test" | "review" | "manual"

EvidencePhase

phase は任意フィールド。ただし type="test" かつ TDD 証跡として使う場合は必須。

"tdd_red" | "tdd_green" | "refactor_verify" | "verification" | "baseline"

phase	用途	期待する exitCode
baseline	実装前の既存テスト確認	0
tdd_red	failing test が期待通り失敗することの確認	!= 0
tdd_green	最小実装で対象テストが成功することの確認	0
refactor_verify	refactor後も対象テスト・関連検証が成功することの確認	0
verification	TDD以外の通常検証	0

tdd_red の exitCode != 0 は失敗ではなく、期待されたRED証跡として扱う。ただし、conclusion には「なぜ期待通りの失敗と言えるか」を必ず書く。

EvidenceItem

{
  "id": "string（例: ev-001）",
  "type": "command | diff | test | review | manual",
  "phase": "baseline | tdd_red | tdd_green | refactor_verify | verification（任意。TDD証跡では必須）",
  "command": "string（type=command/test の場合）",
  "exitCode": "number（type=command/test の場合）",
  "outputExcerpt": "string（出力の一部抜粋）",
  "filePath": "string（type=diff/test の場合）",
  "reviewer": "string（type=review の場合）",
  "conclusion": "string（必須 - この証拠から何が言えるか）",
  "createdAt": "string（ISO 8601）"
}

EvidenceLedger

{
  "claim": "string（完了したという主張）",
  "status": "EvidenceStatus",
  "evidence": "EvidenceItem[]",
  "missingEvidence": "string[]（必須だが欠けている証拠の説明）"
}

TddEvidenceLedger

TDD必須modeの実装タスクでは、EvidenceLedgerに以下のTDD証跡が含まれていること。

{
  "claim": "Task N の実装はTDDで完了した",
  "status": "passed",
  "evidence": [
    {
      "id": "ev-001",
      "type": "test",
      "phase": "tdd_red",
      "command": "pnpm test path/to/test.test.ts",
      "exitCode": 1,
      "outputExcerpt": "Expected failure: function is not defined",
      "filePath": "path/to/test.test.ts",
      "conclusion": "未実装の対象関数が存在しないため、追加したテストが期待通り失敗した",
      "createdAt": "2026-06-21T10:00:00+09:00"
    },
    {
      "id": "ev-002",
      "type" 
       
       
       
       
       
       
       
    
    
       
       
       
       
       
       
       
       
       
    
  
   

手順

ステップ 1: claim を宣言する

完了を主張したい事柄を 1 文で記述する。

例: "ログイン 500 エラーを修正した"

TDD必須modeの例:

"Task 3: validation helper はTDDで実装完了した"

ステップ 2: evidence を収集する

claim に対して実行したコマンド・確認した差分・レビュー結果を記録する。

command type:

# コマンドを実行して exitCode と出力を記録
pnpm test auth.test.ts
# exitCode=0, outputExcerpt="12 passed"

test type: テストファイルのパス、phase、コマンド、exitCode、結果を記録

TDD RED:

pnpm test path/to/test.test.ts
# exitCode != 0, outputExcerpt="期待した失敗理由"

TDD GREEN:

pnpm test path/to/test.test.ts
# exitCode=0, outputExcerpt="1 passed"

refactor verify:

pnpm test path/to/test.test.ts && pnpm typecheck
# exitCode=0, outputExcerpt="pass"

diff type: 変更ファイルのパスと差分サマリを記録

review type: レビュアー名と結論を記録

manual type: 手動確認した内容と結論を記録

ステップ 3: status を計算する

以下のルールを順番に適用する:

1. missingEvidence が 1 件でもある → Completion Gate がブロックされる
2. phase が未指定、または phase != "tdd_red" の EvidenceItem で exitCode != 0 が 1 件でもある → status = "failed"（phase 省略時は tdd_red 以外として扱う）
3. phase = "tdd_red" で exitCode = 0 → status = "failed"（REDになっていない）
4. phase = "tdd_red" で exitCode != 0 かつ conclusion が期待失敗を説明している → RED証跡として有効
5. evidence が空 → status = "unknown"
6. 上記いずれでもない → status = "passed"

ステップ 4: TDD必須modeの不足証跡を判定する

requiresFailingTestFirst=true の場合、以下の欠落は missingEvidence に追加する。

• phase="tdd_red" のEvidenceItemがない
• phase="tdd_green" のEvidenceItemがない
• REDの失敗理由が期待失敗として説明されていない（判定方針: conclusion が非空かつ失敗内容に言及していること。期待との厳密一致は LLM 補助判定とし、機械チェックの最低条件は conclusion 非空 + exitCode != 0）
• GREENの成功コマンド・exitCode・出力抜粋がない
• refactorを行ったのに phase="refactor_verify" がない（判定方針: 直前の tdd_green 証跡以降にソースコード変更ありかつテストコード変更なしを refactor とみなす。機械判定が不能な場合は安全側で refactor_verify を必須化せず任意とする）

ステップ 5: EvidenceLedger を出力する

{
  "claim": "ログイン 500 エラーを修正した",
  "status": "passed",
  "evidence": [
    {
      "id": "ev-001",
      "type": "command",
      "phase": "verification",
      "command": "pnpm test auth.test.ts",
      "exitCode": 0,
      "outputExcerpt": "12 passed",
      "conclusion": "auth 関連テストは全て成功",
      "createdAt": "2026-04-26T10:00:00Z"
    },
    {
      "id": "ev-002",
      "type": "command",
      "phase": 
       
       
       
       
       
    
  
   

保存先

通常検証

/pg verify コマンドは Evidence Ledger を出力形式として使用する。 verify コマンド実行時は本スキルの手順に従い EvidenceLedger JSON を生成し、 docs/working/TASK-XXXX/evidence/verification/ に保存する。

TDD証跡

TDD必須modeでは、TDD証跡を以下に保存する。

docs/working/TASK-XXXX/evidence/tdd/
├── task-001-red.json
├── task-001-green.json
├── task-001-refactor-verify.json
└── task-001-ledger.json

task-N-ledger.json は、RED / GREEN / REFACTOR VERIFY をまとめた EvidenceLedger とする。

参照解決順（導入先で必ずこの順に探す）: 本 Skill が参照する docs/** は上流リポジトリ基準の相対パスであり、install.sh --claude / plugin（Claude marketplace）/ Codex の 3 経路とも配布対象外（解決不可）。(1) 導入先リポジトリの同名パスを探す → (2) 見つからなければ 「正本 <path> を参照できなかった」と明示し、本 Skill 内の記述を代替正本として扱い、推測で内容を補わない。plugin root 配下の探索は docs/** には適用しない: plugin が配布するのは agents / commands / skills / rules 等の定義ディレクトリのみで docs/ を配布対象として認識せず、plugin root 配下に相当する配布物が存在しないため、plugin root 段を置いても必ず空振りする（クラス A の rules 参照が plugin root 配下で解決できるのは rules/ が実際に配布されるからであり、この非対称を docs/** に持ち込まない）。 本 Skill の docs/working/TASK-XXXX/ 配下は参照ではなく出力先であり、導入先リポジトリの同名パス（導入先が独自のディレクトリ規約を持つ場合はそちら）へ作成する。

出力フォーマット

EvidenceLedger JSON を出力する。 status = "failed" または missingEvidence が存在する場合は、 Completion Gate へ「ブロック」として通知する。