verify

検証

verify メンテナンススキルを実行しています。このスキルの役割は、CONTEXT.md ファイルと、それらが説明するコードとのずれを解消することです。ただし、明確に定められた契約をひそかに書き換えてはいけません。

ヘルパースクリプトの実行

このスキルには、独自の scripts/ ディレクトリ（この SKILL.md と一緒にインストールされます）にヘルパースクリプトが含まれています。SKILL_DIR にこのスキルの絶対パスを設定してください。このファイルの末尾にあるこのスキルのベースディレクトリに表示されています。その後、プロジェクトのルートディレクトリからスクリプトを実行してください（スクリプトはプロジェクトの .changes/ ファイルと CONTEXT.md ファイルを対象に処理します）。

SKILL_DIR="<absolute path to this skill's directory>"

以下のすべての node "$SKILL_DIR/scripts/..." コマンドは、この設定に依存します。packages/build/ は参照しないでください。このパスはツールキットの開発リポジトリにのみ存在し、インストール済みのスキルにはありません。

基本姿勢

参照資料を読む前、コンテキストを調査する前、またはサブエージェントを起動する前に、目標と観測可能な成果、影響範囲、制約と避けるべき事項、要件が明確化済みか、部分的に明確化済みか、まだ明確化されていないかを確認してください。その後、references/drift-control.md を読んでください。核心となる非対称性は次のとおりです。

• ソフトな乖離： コードが変更されています。CONTEXT.md を更新して一致させます。コードが正となる情報源です。
• 厳格な乖離： ひそかに書き換えてはいけません。ユーザーに提示してください：意図的な変更（→ 厳格変更プロトコル）か、リグレッション（→ バグとして報告）かを確認します。

この非対称性は必須です。契約に違反するコードに合わせて、厳格な境界の説明をひそかに更新することは、バグを仕様として取り繕う最悪の結果です。

前提条件

なし — verify はアクティブな変更マニフェストがなくても実行できます。メンテナンスツールです。

任意：.changes/active/ にアクティブな変更がある場合、その architecture.md と decisions.md を、対象を絞った調整のための「変更内容」の参照資料として利用できます。

フェーズ 1：調査とスキャン

node "$SKILL_DIR/scripts/context-discover.mjs"

次に、乖離検出ツールを実行します。

node "$SKILL_DIR/scripts/context-verify.mjs" --all [--run-tests]

JSON 出力を解析します。これで、次の情報が得られます。

• 古くなっている CONTEXT.md ファイル（スタンプ付与後にコードが変更されたもの）
• テストの引用を含む、厳格な境界があるファイル
• 欠落している厳格な境界のテストファイル（CI では重大なブロック要因）

フェーズ 2：厳格さに基づくトリアージ

古くなっている各 CONTEXT.md について、調査サブエージェントを使い、実際に何が変更されたのかを把握します。

「次の CONTEXT.md は古くなっています（最後に検証されてからコードが変更されています）。CONTEXT.md を読み、その後、変更された関連コードファイルを読んでください。CONTEXT.md 内の各主張について、現在も有効か、誤りになったか、一部のみ正確かを教えてください。[firmness: firm] とマークされた境界を特に重点的に確認してください。」

サブエージェントに次の情報を渡します。

• CONTEXT.md の内容
• 変更されたファイルの一覧（context-verify の出力にある changedFiles）
• コンポーネントの現在のコード

各乖離を分類します。

乖離	厳格さ	対応
ソフトな説明文が不正確	soft	自動更新
ソフトな境界の説明が変更された	soft	自動更新
ソフトな受け入れ基準が変更された	soft	自動更新
厳格な境界の説明が変更された	firm	ユーザーに提示
厳格な受け入れ基準が変更された	firm	ユーザーに提示
厳格な契約に関わるコードが変更された	firm	ユーザーに提示し、テストも確認

フェーズ 3：ソフトな乖離への対応

ソフトな乖離ごとに、現在のコードに一致するよう CONTEXT.md を更新します。「更新する」とだけ済ませず、新しい状態を正確に記述してください。

ルール：

• 変更された箇所だけを更新します。まだ正確なセクションは書き換えないでください。
• コード変更によって既知のソフトな問題が解消された場合は、その項目を削除します。
• コード変更で新たな技術的負債が生じた場合は、Known-soft-spots に追加します。
• 既存の CONTEXT.md の文体と構成に合わせます。

フェーズ 4：厳格な差異に対処する

厳格な差異ごとに、次の内容をユーザーに提示します。

「厳格な境界で差異が見つかりました： [SEAM-]

CONTEXT.md の記述： [claim] コードの動作： [actual behavior]

これは次のどちらですか？ (A) 契約の意図的な変更 → 厳格な変更プロトコルを実行します (B) リグレッション（仕様ではなくコードに誤りがある） → バグとして報告します」

(A) の場合 — 意図的な変更：

• references/firm-change-protocol.md の厳格な変更プロトコルを適用します。
• 新しい契約を反映するように CONTEXT.md を更新します。
• 厳格な境界テストは、正式な厳格な変更プロセスを通じて更新する必要があることを記録します。
• 有効な変更マニフェストがある場合は、decisions.md に記録します。

(B) の場合 — リグレッション：

• CONTEXT.md は更新しないでください。
• リグレッションの内容を記録します。違反している厳格な境界、違反しているコードパス、検出できたはずの厳格な境界テスト（存在する場合）を記載します。
• リグレッションを修正するため、triage または architect の変更を作成することを推奨します。

フェーズ 5：プロベナンスを再記録する

更新された CONTEXT.md（ソフトまたは (A) による厳格な更新）ごとに、次の手順を実行します。

1. 現在の HEAD の SHA を取得します：git rev-parse HEAD
2. Provenance: validated-at: の行を更新します。

フェーズ 6：概要を提示する

ユーザーに次の内容を提示します。

• 更新したファイル（ソフトな整合）
• 見つかった厳格な差異とその解決方法
• 見つかったリグレッション（未更新、対応が必要）
• 不足していた厳格な境界テストファイル

最終確定の前に、確認を求めます。ユーザーには、更新された CONTEXT.md を少なくとも 1 つスポットチェックしてもらう必要があります。

フェーズ 7：CI コンテキスト向けのレポート

--ci を指定して呼び出された場合（または CI コンテキストから呼び出された場合）、context-verify.mjs の JSON レポートを出力し、次の終了コードで終了します。

• 0 — 厳格な失敗なし
• 1 — 厳格な境界テストファイルの欠落、または失敗が少なくとも 1 つある
• 2 — 古さのみ（警告）

これにより、CI で非対称な判断ができます。厳格な失敗はブロックし、古さは警告します。

verify が行わないこと

• コードの実装変更は行いません。
• architect や specify は実行しません。これらは、アーキテクチャを変更したい場合に使う別のツールです。
• 実行後に CONTEXT.md が 100％ 正確であることを保証するものではありません。これは最善努力による整合処理です。多少の不正確さが残るのは通常のことで、次回の verify で検出されます。

参照ファイル

• references/drift-control.md — 中核となるドリフトモデル
• references/firm-change-protocol.md — 意図的と分類された厳格な差異向け
• references/context-schema.md — CONTEXT.md のフィールドと意味
• references/seam-and-test-taxonomy.md — 厳格な境界テストのルール