tlc-implement

TLC Implement

義務を凍結します。ビルドの制約をなくします。作成していない人に検証してもらいます。

┌────────┐   ┌───────┐   ┌────────┐
│ CHECKS │ → │ BUILD │ → │ VERIFY │
└────────┘   └───────┘   └────────┘
 obligations   yours       always

コーディングエージェントによくある失敗は、要件が有効な義務にならないまま、完了を宣言してしまうことです。それを防ぐには、小規模で凍結された外部の義務セットと、作成者ではない検証者を用意します。そうすれば、予算をモデルの演出ではなく、そこに充てられます。どのように構築するかは、あなた次第です。

入力となるのは tlc-plan が承認した .specs/features/<feature>/plan.md です。承認済みとは、validate_checks.py が必須とする **Approved**: <date> - user: "<their words>" の行があることを指します。そして、それがブリーフのすべてです。それを作成したやり取りの内容が一切ない場合もあります。一方通行の変更がなく、およそ3ファイル未満の変更であれば、プランは不要です。その場合は、## Intent 段落を含む checks.md を作成してください。プランのない、それより大きな変更や、blocks に未解決の質問があるプランは、tlc-plan に差し戻してください。

ルール

参照ファイルを読んでいなくても、以下のルールが適用されます。それぞれの内容はここに記載し、参照先からもここに戻るようにします。

1. 各チェックは、具体的な値を伴う観測可能な主張と、それを確定する根拠を1つずつ含みます。根拠は、終了コードで判定できるテストまたはコマンド、あるいはキャプチャに描かれる状態の場合は、キャプチャと照らして判定する画像（ルール9）です。
2. テストでは、コードが実際に行うことではなく、チェックに記載した内容を検証します。実装を読んでテストを書いてはいけません。
3. テストは、それが証明する主張と同時に変更し、それが証明するコードと同じコミットに含めます。スイートを通すためにテストを変更すると、そのテストが明らかにするはずの失敗を隠すことになります。チェックが間違っている場合は、作業を止めて確認します。
4. validate_checks.py が成功したら、チェックは固定されます。作業の確認や Verifier が不足している要件を見つけた場合は、チェックを追加できます。計画では、Landing、Surface、保存される形状を追加できます。パスと Changes underneath は、それらを変更するコミットで正しい状態に保ちます。
5. Verifier は新規のサブエージェントであり、作者が担当してはいけません。また、機能ごとに必ず1回、screens サブエージェントと並行して実行します。check_proofs.py は機械的な部分、つまりすべての証明の実行と HEAD での合格、ビルド、画像、作業の確認、ミューテーションの検出を判定します。Verifier は判断が必要な部分に時間を使います。誤ったルールでも成功してしまうミューテーション、誰も挙げていない例、基準より緩いアサーションなどです。すべての指摘をコミットで解消し、HEAD で proofs.md が合格した時点で作業は完了です。
6. ミューテーション数は checks.md の Mutations: に宣言します（デフォルトは3）。この数で Verifier が検証するルールの数が決まりますが、作業の品質が決まるわけではありません。コード品質、各チェックの根拠となるテスト、完全な Coverage の結合は、N の値にかかわらず必要です。チェックは最低限の基準です。チェックに記載されていないエッジケースやガードも、作業の対象です。
7. 完了のゲートはスクリプトです。validate_verification.py が終了コード0を返します。最終報告はその最終行から始めます。ゲートが失敗している場合は、最初にそのことを伝え、読者に見つけさせてはいけません。
8. 承認された計画は、ローカルでの編集とコミットを許可します。git push、デプロイ、本番データの変更には、その操作について明示的な許可が必要です。
9. キャプチャに描かれる状態には、画像を1枚用意します。 作者は、その状態にして、キャプチャと同じサイズ（拡大率に対するピクセルサイズ）のブラウザーウィンドウから <capture>.running.png をキャプチャの隣に保存します。ウィンドウの幅が違うとページのレイアウトが変わり、あとから画像のサイズを変更するとその違いが隠れてしまいます。アプリを再度開いて判定することはありません。screens サブエージェントがファイルを判定し（verify-screens.md）、画像内の文字がキャプチャより小さく見える場合は、サイズ変更された画像と見なして撮り直します。## Differences from the source に記載された点を除き、キャプチャと一致させます。キャプチャに描かれていない状態と、機能によって変更されない既存の画面は、テストまたは walk の証明で立証します。画像も判定者も不要です。
10. 計画で拘束力のあるものとして引用されたキャプチャ、フレーム、ライブサイトは、ユーザーだけが変更できます。そこに描かれた内容を削除、改名、または変更する場合は、ユーザーに確認します。その決定を .specs/STATE.md に記録し、計画の ## Differences from the source に Confirmed: y - AD-NNN と記載します。
11. 実行の記録はファイルに残し、チャットはコンパクション後に引き継がれません。 作業中にユーザーが確定した内容は、その発言があったターンに checks.md の **Settled mid-build:** 行へ記録します。各サブエージェントは、起動する前に **Dispatched:** 行へ記録します。コンパクション後、または新しいセッションでは、このファイルと現在のフェーズの参照ファイルを読み直し、ファイルの内容をもとに作業を再開します（memory.md）。

Configuration

プロジェクトでは AGENTS.md または同等のファイルで宣言します。checks.md では、その数を Mutations: 行に転記します。

## tlc-implement

mutations: 3

部分	実行内容	検出できないこと
check_proofs.py（常時）	各ランナーで各証明を HEAD に対して1回実行し、各チェックをフィルターが選択したテストに照合し、Build: コマンド、画像、操作手順を確認して、ミューテーションを注入します	誤った理由で成功するテスト
Verifier（常時）	ルールが存在する場所に N 個のミューテーションを適用し、誰も指定していない2つの例、基準より緩いアサーション、拘束力のあるキャプチャと矛盾するチェックを調べます（verify.md）	ミューテーションで検証していないルール
screens サブエージェント（基準がキャプチャを参照する場合）	各キャプチャを作成者の画像と照合し、名前付きの HEAD で各行を same または differs と記録します（verify-screens.md）	間隔、色、フォントの太さ、スクリーンショットで分からない細部、キャプチャにない画面

画面の検証ではミューテーションを使いません。誤った実装による損失が最も大きい部分に N を割り当ててください。機能に対して N が少なすぎると思われる場合は、その旨を1行で述べ、ユーザーが増やせるようにします。

Artifacts

.specs/
├── STATE.md                    # decisions log (AD-NNN)
├── LESSONS.md                  # rendered by scripts/lessons.py - do not hand-edit
├── lessons.json                # machine-owned
└── features/<feature>/
    ├── plan.md                 # from tlc-plan; read, and kept true
    ├── checks.md               # claims + proofs, the coverage join, swept, handoff
    ├── captures/               # binding source files, and the author's <capture>.running.png
    ├── screens.md              # the screens sub-agent's inventory and verdict, per picture
    ├── proofs.md               # written by check_proofs.py: every proof and mutation at HEAD
    ├── mutations.json          # the Verifier's mutations, re-run after the fix
    └── verification.md         # the Verifier's findings, each closed by a commit

Phases

フェーズ	作成するもの	参照先
Checks	証明付きの主張、すべてのセットをメンバーごとに結合したもの、網羅した9つの側面	checks.md
Build	チェックに基づくテスト、コード、コミット、操作して保存した画面	build.md
Verify	ルール5	verify.md、verify-screens.md

決定事項、再開方法、教訓については、memory.md を参照してください。

Scripts

<skill-dir> は、この SKILL.md を含むディレクトリとして解決し、 python3 <skill-dir>/scripts/<name>.py を実行します。cwd がプロジェクトのルートでない場合は --root を渡してください。終了コードがゼロ以外の場合は停止して修正します。スクリプトを読むのではなく実行してください。変更すべき内容はスクリプトのメッセージに示されます。

タイミング	コマンド
ビルドを開始する前	validate_checks.py <feature> - プランに **Approved**: 行があることも要求します
各コミットの前	check_commit.py --message "<msg>"
Verifier をディスパッチする前と修正後	check_proofs.py <feature> [--mutations <mutations.json>]
完了を宣言する前	validate_verification.py <feature>
チェックを記述する前とゲート通過後	lessons.py ...
バリデーターまたはテンプレートの編集後	selftest.py

selftest.py は、ゲートの各ルールにつき1回、scripts/fixtures/ のフィクスチャにミューテーションを適用し、すべてのミュータントが検出されることを要求します。フィクスチャは、成果物一式が合格する実例でもあります。

Requires

必要なもの	用途	ない場合
Python 3.8 以降（標準ライブラリのみ）	すべてのスクリプト	ゲートは実行されませんが、各フェーズは適用されます
git	mutate.py と check_proofs.py（HEAD、クリーンなツリー）	ミューテーションと HEAD のチェックは実施できません。その旨をレポートに記載してください
サブエージェント	Verifier と screens サブエージェント	新しいセッションでそれぞれのファイルを実行し、self-verified と記載します。ゲートから警告が出ます
画像を読み取れるモデル	screens サブエージェント	画像とキャプチャをユーザーに渡します
エージェントが操作できるブラウザー	<capture>.running.png の保存と操作手順	手順をユーザーに渡します

テストランナー：check_proofs.py は bun、vitest、jest、pytest、go test をそれぞれ1回の実行にまとめます （scripts/runners.py）。それ以外のコマンドは単独で実行し、終了コードで判定します。

Output

成果物を作成し、フェーズの説明はしないでください。まず判定を示し、決定事項を明確に述べてください。 セクション見出しは英語のままにし、文章はプロジェクトの文体に従い、識別子は翻訳しないでください。