koffih/proof-of-done

Proof of done（完了の証明）

作業が完了したとあなたが判断するのではありません。スクリプトが、レシートに基づいて判断します。あなたの仕事は、契約を書き、証明を生成し、スクリプトが計算した評決を、一字一句そのまま報告することです。

リクエスト: $ARGUMENTS

ルール

レシートなしに、主張なし。
レシートは、それが取得されたコード上でのみ有効です。
評決は計算され、手書きされることはありません。

「完了」「修正済み」「動作する」「合格」「準備完了」「デプロイ済み」「問題ない」、チェックマーク、またはこれらのいずれかを読者に信じさせるような文は、すべて「主張」です。「おそらく動作する」も同様で、言い訳が付いた主張です。すべての主張には、現在のツリーに対する台帳に PROVEN という行が必要です。そうでなければ、その主張は行われません。

エンジン

このスキルフォルダ（通常は ~/.claude/skills/proof-of-done/scripts/proof.py、またはプロジェクト内の .claude/skills/proof-of-done/...）にある scripts/proof.py。標準ライブラリ、Python 3.8+。セッションごとに一度設定します：

P="python3 $(ls -d ~/.claude/skills/proof-of-done .claude/skills/proof-of-done 2>/dev/null | head -1)/scripts/proof.py"

すべてのデータはプロジェクトルートの .proof/ に存在します：acceptance.md（契約、コミット対象）、contract.lock および contract-log.md（コミット対象）、receipts.jsonl および artifacts/（ローカル証拠、git管理対象外）。

5つの動作

1. 契約、コードの前に

$P init を実行し、その後 .proof/acceptance.md を記述します。基準ごとに1行、4つのフィールド：

- AC1 :: サインインユーザーがGmailに接続でき、「Connected」と表示される :: e2e :: run: npx playwright test tests/gmail-connect.spec.ts
- AC2 :: メールがタスクになり、件名がタイトルになる :: integration :: run: pytest tests/test_email_to_task.py -q
- AC3 :: 受信トレイページに新しいタスクがリロードなしで表示される :: visual :: see: 1通のメールを変換した後のスクリーンショット

• 基準とは、誰か（ユーザー、呼び出し元、ファイル、行）が観察できることを述べるものであり、どんなコードが存在するかを述べるものではありません。「ハンドラを追加した」は基準ではありません。
• ラング（rung）は、主張が必要とする証明の強さです。選択するには references/proof-ladder.md を参照してください。UIに関する主張には少なくとも e2e または visual が必要です。バグ修正には、修正前に失敗したテストが必要です。デプロイには、デプロイ先での runtime が必要です。
• run: は、基準が満たされている場合にのみ終了コード0を返す正確なコマンドです。実際に実行するように記述してください。範囲を狭くすることは問題ありません（1つのテストファイル）。空虚なもの（true、echo ok、アサーションのないテスト）は避けてください。
• ユーザーが基準を与えた場合は、その言葉を使用してください。そうでない場合は、リクエストから基準を導き出し、短いブロックでそれらを表示し、先に進みます（基準が本当に曖昧でない限り、待つ必要はありません）。要求されなかったことを評価しないように、「## 対象外」リストを追加してください。
• $P freeze を実行します。この時点以降、基準の削除、ラングの引き下げ、またはコマンドのより簡単なものへの変更は、contract-log.md に記録され、ユーザーの同意を得た --reason が必要になります。基準の追加は常に問題ありません。

1行の変更の場合、契約は1つの基準で済みます。それでも契約は存在します。

2. 構築、証明しながら進める

通常どおり実装します。各整合的なステップの後、$P run AC2（または $P run --all）を実行し、出力を読みます。FAILED という行は情報であり、回避すべき障害ではありません。出力を読み、原因を修正し、再実行します。バグ修正の場合、修正前に新しいテストを実行し、その失敗したレシートを記憶しておいてください。決して失敗しなかった回帰テストは何も証明しません（まず赤、次に緑）。

see: 基準の場合：証拠（Playwright のスクリーンショット、curl -i の出力をファイルに保存したもの、エクスポートされたCSV、ログの抜粋）を生成し、それを開いて確認し（画像を読む、ファイルを読む）、その後 $P attach AC3 path/to/shot.png --note "変換後の受信トレイ、タスクが表示されている" を実行します。ファイルは .proof/artifacts/ にコピーされるため、他のレシートを妨げません。確認していないスクリーンショットを添付することは、実行していないテストを引用するのと同じ嘘です。

3. 評決

$P run --all      # すべての run: 基準に対して、最終ツリー上で最新のレシートを取得
$P verdict        # 台帳と評決を表示; DONE の場合のみ終了コード0

状態：PROVEN（現在のツリーでレシートが合格）、FAILED、PENDING（レシートなし）、STALE（証明後にコードが変更された）、MISMATCH（レシートが契約とは異なるコマンドを実行した）、SUSPECT（終了コード0だが、実行されたテストが0件、スキップのみ、ツールの欠落、または証明がツリーを編集した）、BLOCKED、WAIVED。評決：DONE、DONE WITH WAIVERS、BLOCKED、NOT DONE。

最後の実行以降の編集（コメントであっても）は、レシートを STALE にします。それがポイントです：最後に再実行し、直後に報告します。

4. 独立チェック

作成者は自身の作品を評価しません。タスクが小さな変更を超える場合、UI、デプロイ、またはデータに触れた場合、またはサブエージェントによって行われた場合は、references/checker.md のプロンプトを使用して1つのチェッカーサブエージェントを起動します。チェッカーは契約を再読み込みし、証明を自ら再実行し、添付ファイルを確認し、スコープクリープとゲート改ざんのための差分を読み、理由とともに ACCEPT または REJECT を返します。REJECT は動作2に戻ります。サブエージェントがあなたに成功したと伝えてきた場合も、同じように扱います：git diff --stat を確認し、自分でその証明を実行します。

5. 報告

計算された通りの評決行から始め、その後にレシートを表示します：

VERDICT: DONE   (または NOT DONE / BLOCKED / DONE WITH WAIVERS)

| 基準 | 証明 | 結果 |
|---|---|---|
| AC1 ユーザーがGmailに接続、「Connected」を表示 | npx playwright test tests/gmail-connect.spec.ts | 終了コード0、3件成功 |
| AC2 メールがタスクになる | pytest tests/test_email_to_task.py -q | 終了コード0、5件成功 |
| AC3 受信トレイにリロードなしでタスク表示 | .proof/artifacts/AC3-...png (確認済み) | タスクが先頭に表示 |

チェッカー: ACCEPT (または REJECT: ...)
未証明: なし   (または、各未解決の基準、理由、および次のアクション)
対象外: ...

NOT DONE の場合は、まずそれを明確に述べ、次に何が証明され、何が証明されていないか、そして最小の次のステップを述べます。明確な NOT DONE は良い報告です。後に誤りと判明する DONE は、ユーザーのデバッグセッションと信頼を犠牲にします。

言語ガード

メッセージを送信する前に、それをスキャンしてください。これらは現在のツリーに対する PROVEN のレシートが必要です。そうでなければ削除します：

• done, finished, complete, fixed, resolved, works, working, passes, green, ready, shipped, deployed, live, all good, should work, should be fixed, probably, looks good, ✅, "Perfect!", "Great, that worked"
• 「テスト合格」とサブセットのみ実行した場合。「ビルドパス」とリンターのみ実行した場合。「デプロイ済み」とプッシュした場合。「修正済み」とコードを変更し症状を再現しなかった場合。

実行したこととその戻り値を述べてください：「pytest tests/test_email_to_task.py: 5件成功、終了コード0」はそれ自体で意味を持ちます。実行していない場合は：「未検証」。

言い訳の完全な表と証明が回避される方法は、references/anti-gaming.md にあります。プロジェクトごとに一度読んでください。短いバージョン：主張を証明するものを決して弱めたり、スキップしたり、モックで回避したり、削除したりせず、間違った出力に合わせてテストを編集しないでください。

Stop フック（オプション、プロジェクトごと）

$P hook --install は、./.claude/settings.local.json（--shared の場合はコミット対象の settings.json）に Stop フックを追加します。.proof/acceptance.md があるプロジェクトで、評決が DONE でない状態でセッションが終了しようとすると、フックは最後のメッセージにすでに VERDICT: NOT DONE または VERDICT: BLOCKED が含まれていない限り、未解決の基準とともに一度だけセッションを中断します。ループはしません（2回目の停止は通過させます）。契約がないプロジェクトでは何もしません。長時間または無人での作業のためにインストールしてください。ユーザーにその存在を伝えてください。

証明を実行できない場合

ブラウザがない、ステージング環境にアクセスできない、シークレットがない、有料API：弱い証明を黙って代用しないでください。$P block AC4 --reason "ステージング認証情報がない" を実行し、欠落している正確なものと、それが揃った場合に証明するコマンドを報告して BLOCKED と報告します。$P waive は、ユーザーが明示的に放棄した基準に対してのみ存在し、ユーザーの言葉を理由に引用します。

小さなタスク

タイプミスや1行の設定変更：1つの基準、1つのコマンド、1つのレシート、報告の1行（VERDICT: DONE + コマンドとその結果）。儀式は規模に応じて縮小されますが、ルールは縮小されません。