post-edit-verification

編集後の検証

コンポーネントファイルを編集した後、変更が反映されたことを確認するためにファイル全体を読み直したくなるのは自然なことです。ただし、デフォルトでは読み直さないでください。 コンポーネントの JSON ファイルは、1 行に圧縮されたドキュメントで、サイズが 20～100 KB になることも多く、編集のたびに読み直すと、実際の作業に必要な親の会話コンテキストを消費します。同じ役割を果たす、より軽量なシグナルがいくつかあります。以下の順に適用してください。

フック置き換えの背景。 Mitch のリポジトリには、PostToolUse フック（hooks/validate-component.py）があり、追跡対象のコンポーネントの拡張子を持つファイルに対する Edit／Write を自動的にブロックしていました。このフックは、description が null、空、または 100 文字を超えている場合や、JSON の解析に失敗した場合にブロックしていました。Datex Skills リポジトリには PostToolUse の仕組みがありません。スキルはツールイベントによって自動的に呼び出されないためです。このスキルがその代わりを務めます。すべてのコンポーネント作成スキルは末尾に 「編集後、post-edit-verification を呼び出してください」 と記載しているため、同じ 2 つのプラットフォーム不変条件をハーネス層ではなくスキル層の 1 か所で適用できます（DRY）。環境にハーネスレベルの保存ゲートフック（不正なコンポーネントの保存をブロックする PostToolUse バリデーター）がインストールされている場合、フックが反応しないことは、ハーネスレベルのゲートを通過したという肯定的なシグナルとして扱ってください。フィードバックがなかったと見なしてはいけません。以下のスキルチェックは、引き続きどの環境でも使える最低限の確認事項です。

プラットフォームの不変条件（最低限のチェック）

この 2 つのルールは、すべてのコンポーネントファイルで必須です。以前のフックが適用していたルールであり、このスキルの最低限の基準でもあります。どれほど些細に見える編集でも、呼び出すたびに両方を確認する必要があります。

1. description があり、プラットフォームの上限以内であること。 トップレベルの description は null ではなく、空でなく、100 文字以下でなければなりません。Footprint プラットフォームでは description を最大 100 文字の SQL カラムに保存するため、上限を超えると SQL の切り詰めエラーが発生してインポートに失敗します。正式な「説明は必須」というルールについては ../datex-studio-conventions/defaults.md を、SQL の 100 文字制限については ../datex-studio-conventions/file-format.md を参照してください。このフィールドがない場合や長すぎる場合は、同じ編集サイクル内で修正してください。補完するかどうかをユーザーに尋ねず、100 文字以下の説明を作成してください（作成した値と同様、ユーザーは後から文言を変更できます）。

2. JSON が正しく解析できること。 編集後も、ファイルは有効な JSON でなければなりません。python -c "import json; json.load(open(r'<path>')); print('OK')" を実行してください。括弧の不一致、余分な引用符、不正なエスケープシーケンスはここで検出されます。無料で実行でき、親の会話コンテキストも消費しません。同じファイルに対して一連の編集を行った後に 1 回実行し、編集のたびには実行しないでください。

いずれかの不変条件に違反している場合、編集は完了していません。完了を報告したり次に進んだりする前に違反を修正し、再検証してください。

検証スタック（コストの安い順）

1. Edit ツールの成功メッセージ。 ツールは「The file ... has been updated successfully.」と報告します。このメッセージは、old_string が一致し、そのまま置き換えられたことを意味します。正確な old_string を作成し、ツールが成功を報告したなら、テキストの編集は完了しています。残る確認事項は、結果が構造的にも意味的にも妥当かどうかです。これは次のレイヤーで確認します。

2. JSON の解析チェック。 python -c "import json; json.load(open(r'<path>')); print('OK')"。編集によって JSON の外枠（波括弧の不一致、余分な引用符、エスケープエラー）が壊れていないことを確認します。無料で、親コンテキストのコストもかかりません。同じファイルに対する編集をひと通り行った後に一度実行し、編集のたびには実行しないでください。これがプラットフォーム不変条件 #2 です。

3. 説明のチェック。 JSON の解析後、description が null ではなく、空でなく、100 文字以下であることを確認します。

   python -c "import json; d=json.load(open(r'<path>'))['description']; assert d and len(d) <= 100, (d, len(d) if d else 0); print('OK', len(d))"
   

   これがプラットフォーム不変条件 #1 です。 アサーションに失敗した場合は、同じ編集サイクル内でフィールドを修正してください。

4. コンテキスト付きの Grep。 特定の編集が意図した場所に反映されたことを確認するには、ファイル全体ではなく、変更したセクションを名前で指定します。

   • Grep "while \(pickTasks" -C 30 は、30 KB のファイル全体ではなく、ループの前後約 60 行を返します。
   • Grep "concurrency_limit" -C 5 は、スキーマ全体を出力せずに inParam が追加されたことを確認します。
   • 精度を損なわずに、コンテキスト量を桁違いに削減できます。

5. component-validator サブエージェント。 大規模ではないものの重要なリファクタリング後に、実質的な構造検証を行う場合に呼び出します。これは最終ゲートレビューで行われるような監査を、ファイルごとに実施するものです。サブエージェントは独自のコンテキストでファイルを読み取り、親に返すのは指摘事項の一覧だけです。グリッドの場合は、代わりに grid-validator を使ってください。汎用ディスパッチャーでは検出できないグリッド固有の注意点（外枠の形状、テキスト表示の型変換、5 か所の不変条件）を確認できます。

6. ファイル全体を再読込する（最後の手段）。 構造全体を最初から最後まで見る必要が本当にあり、何を Grep すればよいかまだ分からない場合に限り、Read を使ってください。たとえば、まれなレイアウトの問題を追跡する場合や、バリデーターの指摘事項が空でも何かがおかしいと感じるケースのデバッグなどです。最初ではなく、最後に確認する手段にしてください。

component-validator エージェントに委任する場合

委任する場合：

• 単一のコンポーネントファイルで、重要な編集（ループのリファクタリング、スキーマ変更、複数ステップの修正）を完了した場合。
• ファイルが最小化された状態で 20 KB を超える場合（大半のコンポーネントファイルが該当します）。
• 自分で自由形式の抜き取り確認を行うより、構造化された指摘事項の一覧が必要な場合。
• 変更が、型の Pre-Flight Checklist で確認される description、inParams / outParams、accessModifier、その他の契約フィールドに及んだ場合。

委任しない場合：

• 編集が 1 文字または 1 行だけの変更の場合。Grep -C のほうが速く済みます。
• 編集の途中で、次の変更を決める必要がある場合。親にはローカルコンテキストが必要です。
• 変更が書式や空白だけの場合（バリデーターにそのルールはありません）。
• 前回の編集後にすでにバリデーターを呼び出しており、その後の変更が小規模なものだけの場合。

グリッドファイル（*-grid.json）では、component-validator より grid-validator を優先してください。編集の規模にかかわらず、グリッドでは必須です。グリッド固有の注意点（外枠の形状、動的フィルターのミラーのずれ、lookupcode/id の同期漏れ）は、汎用ディスパッチャーでは検出できないためです。

リスクに応じた検証

変更のリスク範囲に応じて、検証コストを割り当てます。プラットフォームの不変条件（上記の #1 と #2）が最低限の基準となり、すべての行に適用されます。右側の列には、この最低限の基準に加えて実施するチェックを記載しています。

編集の種類	検証（2 つのプラットフォーム不変条件に加えて実施）
1 文字の修正／コメントの修正	Edit の成功メッセージを信頼します。それ以上は不要です。
コントラクトではないフィールドの単一ブロックの内容変更	（最低限の基準のみ。）
スキーマまたはコントラクトの変更（inParams／outParams／accessModifier）	変更したスキーマを対象に Grep -C を実行します。
同じファイル内で複数箇所を編集するリファクタリング	編集ごとではなく、一連の編集の最後に component-validator サブエージェントを実行します。
コンポーネントをまたぐ変更（複数ファイルを連携して変更）	各ファイルに対して最後に component-validator を実行し、さらに component-wiring-check スキルを使用します。
グリッドファイル（*-grid.json）の編集	grid-validator サブエージェントを使用します（必須。グリッドでは汎用バリデーターの代わりとなります）。

検証は確認ではなく、保険です。リスクに応じて保険料を設定します。ただし、最低限の基準を省略してはいけません。

参考資料

• ../datex-studio-conventions/defaults.md — 「説明は必須」という正式なルール（null ではなく、空でなく、100 文字以内）。
• ../datex-studio-conventions/file-format.md — description の SQL における 100 文字制限や、単一行の最小化 JSON 形式の規約を含む、正式なファイル形式のルール。
• ../datex-studio-conventions/universal-checklist.md — このスキルの 2 つの不変条件を超える、より包括的な横断チェックリスト。このスキルでは最低限の基準（説明＋JSON 解析）を適用し、エスカレーション時には component-validator が全項目を確認します。
• component-validator — 型ごとの汎用監査ディスパッチャー。重要な編集のエスカレーション先です。
• grid-validator — グリッド固有の監査ツール。編集規模にかかわらず、*-grid.json では必須です。