hrt-align-consistency-review

hrt-align-consistency-review

コードを書く前に、すべての tempa-spec 成果物が相互に矛盾せず、要件に忠実であること、そしてエージェントが相互に照合しただけでなく、人間が実際に読んでいることを確認します。

1 サイクルの流れ：ALIGN（このエージェントが成果物間の一貫性を確認）→ VERIFY（このサイクルの ALIGN で少なくとも 1 件の HIGH 指摘があった場合に限り、新しいコンテキストのサブエージェントが ALIGN 自身のマップと修正を再確認）→ WALKTHROUGH（仕様と設計を中心にまとめた内容を人間に提示し、変更が必要な点があるかを一度だけ尋ねる）。WALKTHROUGH からのフィードバックは ALIGN に戻ります。WALKTHROUGH のラウンドで新たな指摘がなくなるまで、またはユーザーが早期に承認するまで繰り返します（「ループの終了」を参照）。各サイクルの開始時にサイクル番号を報告します。ループが終了しないまま 3 サイクルを終えたら、続行するか承認するかをユーザーに尋ねます。独断で終了してはいけません。

ALIGN

1. すべての成果物を読み直します：proposal.md、specs/**/*.md、design.md、tasks.md。openspec validate --strict と hrt-artifact-lint スキルを実行します。構造と網羅性は lint の担当です：spec の構造、capability と spec ファイルの対応、design の Covers: 対象、各シナリオをタスクグループが網羅していること（および各グループの Covers: に実在する名前があること）、すべての脅威に否定的なシナリオまたは名前付きチェックで対応していること、proposal のサイズと形式です。lint の ERROR はすべて直接修正し、それぞれを MECHANICAL finding として記録します。ERROR に複数の妥当な修正方法がある場合（たとえば、複数のグループで対応可能なシナリオなど）は、代わりに DECISION finding として記録します。lint が問題なく完了したかどうかを記載し、WALKTHROUGH 用に Size facts: 行を保持します。design.md は必須です。存在しない場合は HIGH finding です。
2. 一貫性マップを作成します。以下の各観点について、分類に進む前に、確認した内容と見つかったことを列挙します。判断が必要なのは以下の観点です。残りは lint がすでに確認しているため、lint を実行できなかった場合を除き、手作業で再確認しないでください。
   • proposal <-> design と specs：両方向。順方向：proposal.md の Why に記載されたすべての成果と Capabilities の各項目が、specs のシナリオで扱われ、design で説明されていること。逆方向：specs と design が、proposal にない capability や動作を追加しておらず、Out of Scope に記載された内容がそれらに含まれていないこと。lint は、各 capability に spec ファイルがあることを確認済みです。ここでは、内容が一致しているかだけを判断します。LLM による判断のみ。
   • specs <-> design（seam を含む）：design が各要件の実現方法を説明し、要件と矛盾していないこと。LLM による判断のみ。Seams：specs/** にある各 #### Scenario に対して、そのテストが結び付けられる seam が design.md の Shape / Seams セクションにあること。ステップ 1 の lint は、各 seam の Covers: 対象が実在する要件またはシナリオを指していることを確認済みです。ここでは、順方向（各シナリオに、そのテストが結び付けられる seam があるか）と、その結び付けが実際に適切かだけを判断します。Shape / Seams が「新しいコード面なし」という一行の注記（純粋な設定／データ変更）の場合に限り、seam の確認は省略します。ステップ 1 の lint がセキュリティゲートの WARN を出した場合（proposal/specs に信頼境界を示すキーワードがあるが、[Threat の項目も Security pass: skipped - <reason> の行もない場合）、その境界が実在するかを判断します。実在するのに脅威リストがない場合は MEDIUM、skip の理由が specs と矛盾する場合も MEDIUM です。WARN がなくても、specs が扱う各信頼境界（アップロード、ログイン、Webhook など）に [Threat の行があることを確認します。lint は脅威の行が1つでもあれば警告を抑制するため、未対応の境界があれば MEDIUM です。
   • design <-> tasks：両方向。順方向：design.md のすべての Decision に、それを実行するタスクがあり、design に記録された前提条件が早期のグループとして含まれ、それを必要とするスライスが依存していること。逆方向：design のスコープや seam を超えるタスクがなく、各グループが RED から GREEN へ進められる規模と順序であること（デモできないほど粒度が粗いグループや、別グループのコードを必要とするのにその旨が記載されていないグループは finding です）。lint はシナリオと脅威の網羅性を確認済みなので、繰り返し確認しないでください。LLM による判断のみ。
   • tasks のグラフ：tasks.md に Depends on: 行がある場合を除き、省略します。ステップ 1 の lint は構造（不正な値、不明な ID、循環）を確認済みです。ここでは、宣言された依存関係が正しいかだけを判断します。宣言された依存関係が、同時に実行されるグループ間の唯一の分離手段だからです。別グループのコードやテストを必要とするのに Depends on: に記載していないグループや、依存関係の経路がなく同じファイルを編集するグループの組み合わせがないか確認します（design.md の Shape / Seams と tasks に記載されたファイルを参照）。依存関係の欠落は危険な方向です。
   • design/tasks -> codebase：design.md または tasks.md が既存システムについて述べる具体的な主張（すでに存在する、または変更が必要だとする関数、メソッド、モジュール、ファイル、エンドポイント、スキーマ、設定）を、推測ではなく実際のコードベースと照合します。存在確認には必ずツールを使用します（codegraph > codebase-memory-mcp > ripgrep）。成果物におけるコードの説明が正確かだけを判断します。確認した主張とその結果をすべて align.md に記録します。サイクル 2 以降では、前回のサイクル以降に新規追加または変更された主張だけを再確認します。align 中にコードベースは変更されず、コードは apply で書かれるため、前回のサイクルで検証済みで変更のない主張は引き続き有効です。
   • サイクル 2 以降：前回の WALKTHROUGH で提起された内容も取り込み、それぞれを注記ではなくマップ上の独立した項目として扱います。
3. 上記すべての観点に適用するルール：機械的に確認するのは存在／参照／構造の面（X が存在するか、X が参照されているか、形式が正しいか）だけです。意味的な面（X が実際に意図を満たしているか）は機械的に確認しません。キーワードの一致は、その判断の代わりにはなりません。
4. STOP。まだ分類しないでください。先に進む前に、上記の5つの観点すべて（および引き継いだ WALKTHROUGH の項目があればそれら）について、一貫性マップが完成していることを確認してください。
5. すべての finding を分類します。まず影響の判定：未修正の場合に下流で何が起きるかを具体的に示せる場合に限り、HIGH または MEDIUM とします。たとえば、実装者が矛盾を誤って実装する、要件がテストされずにリリースされる、apply が誤解を招くコードベースの説明に従う、などです。それ以外はすべて LOW です。たとえば、「design.md と tasks.md で同じものを別の語で表現している」「要件をまとめ直したほうが読みやすい」は、下流での問題を示していません。
   • HIGH：成果物間の矛盾、proposal にない capability を追加する design、OpenSpec の解析を妨げる構造エラー、proposal.md の Why に記載されたのに spec のシナリオで実行されない成果、コードベースに関する design/tasks の主張（参照される関数、モジュール、ファイル、API）が実態と一致しない場合。
   • MEDIUM：網羅性が不十分、重要な技術的選択に design の判断がない、タスクの粒度が粗すぎる／順序が不適切、Decision を実行するタスクがない、proposal が示唆するエッジケースにシナリオがない、結び付け可能な seam がないシナリオ、design のスコープや seam の範囲外のタスク、specs が扱うのに [Threat の行がない境界。
   • LOW：用語の揺れ、表現、書式、順序、軽微な欠落など、影響の判定を通過しなかった実際の問題。 要件が曖昧またはテスト不可能であることは、specs の段階における Structural Auditor の finding であり、align の finding ではありません。
6. すべての finding に MECHANICAL または DECISION のタグを付けます。
   • MECHANICAL：正しい修正方法が1つだけで、スコープや意図に関する判断を必要とせず、さらに再実行可能な決定的アンカーがあること（修正前後を確認できる grep／regex／件数など。例：ハッシュタグ数、チェックボックス形式、kebab-case 名の不一致、タスクの並べ替え）。アンカーがなければ「明らかに機械的」でも不十分です。条件を満たすように見えてもアンカーがない finding（例：2つの用語が同じ意味かを判断する必要がある「用語の統一」、明らかに見えてもシナリオの欠落に関する判断）は DECISION です。
   • DECISION：妥当な解決方法が複数ある、スコープや意図に関わる、または MECHANICAL の条件を満たすように見えてもアンカーがないものです（例：design と spec の矛盾、シナリオのない成果、脅威の行がない境界、上記のアンカーがないケース）。「保留する」「不一致を容認する」は妥当な解決方法に含まれません。ただし、適切な作成者が別の選択をし得る場合は、明確な修正方法が分かっていても DECISION のままです。
7. 今回のサイクルの finding を HIGH／MEDIUM／LOW に分類して提示し、それぞれに MECHANICAL または DECISION のタグを付け、問題を明確に述べます。
8. finding を解決します。
   • MECHANICAL finding（重要度を問わず）は直接修正し、変更内容を記録します。
   • 個別の回答が必要なもの：HIGH の DECISION finding と、proposal.md がすでに確定したスコープを変更する DECISION finding は、一方向の変更です（データ移行や破壊的なスキーマ変更、保存データの削除、公開済み API やイベント契約の変更、他のコードが読み取る設定やフラグの削除、手作業で元に戻す必要がある手順など）。また、重大度の高いセキュリティ上のトレードオフも該当します。黙って編集してはいけません。また、報告のためにスキルを終了してはいけません。該当する項目をすべてまとめて1つのメッセージで提示します。各項目では、まずトレードオフを中立的に説明します（何が矛盾していて、妥当な解決方法は何か）。その後に推奨する解決方法を述べます。ユーザーが選択肢を検討できるよう、推奨は後にしてください。推奨は、意図の根拠として proposal.md を参照します。ユーザーは各項目に個別に回答します。単なる「ok」では回答したことになりません。各項目について、実際の解決方法または理由を明記した明示的な保留を得てください。未対応の HIGH が残ったまま先に進んではいけません。
   • Digest：上記が解決した後、それ以外のすべての DECISION finding（MEDIUM および LOW）を1つのダイジェストメッセージにまとめます。それぞれに推奨する解決方法と、1行の理由を記載します。ユーザーが「ok」と答えればすべてを承認したことになります。例外がある場合はユーザーが指定します。LOW finding は最大5件まで提示し、残りは align.md の Known Issues に記録して、ダイジェストには件数を記載します。未解決の finding は最後に Known Issues に記載します（「希望があれば対応します」）。サイクルの進行を妨げることはありません。
   • どちらのメッセージも、plain-language-writing スキルの COMMS ルールに従う必要があります。
9. 今回のサイクルの ALIGN 結果を align.md に追記します。finding（重要度 × MECHANICAL／DECISION）、適用した機械的修正、ユーザーが行った決定（明示的な保留を含む。ユーザーが示した理由も記載）を含めます。記録した各決定と解決済みの HIGH には、参照元の場所（ドキュメントとセクション。例：「proposal.md > What Changes」）を付けます。apply はまず align.md を読み、該当する箇所を正確に参照します。ユーザーがチェックは誤りまたは過剰だった（lint ルール、観点、レビュー工程、変更規模の質問など）と述べた場合は、Gate Records の下に、ゲート、その入力、その出力、ユーザーの対応（承認、却下、編集）を1行で記録します。これによりゲートを有効に保ち、保守担当者にデータを提供できます。この記述は plain-language-writing スキルの ARTIFACT ルールに従う必要があります。
10. 今回のサイクルのすべての HIGH issue は、ALIGN の完了前に次のいずれかの結果になっている必要があります。修正済み（機械的な修正、またはユーザーが選んだ解決方法）、あるいはユーザーが理由を記録したうえでスコープ外と明示したもの（これは保留ではなく解決済みとして扱います）。単なる「後で対応する」では不十分です。その場合は、各項目がこのどちらかの結果になるまで、ステップ 8 の解決に関するやり取りを続けてください。今回のサイクルのマップにあるすべての HIGH がいずれかの結果になってから、VERIFY に進みます。

VERIFY

ALIGN は自身の指摘を分類し、自身で機械的な修正を適用しますが、その作業を独立して確認するものはありません。VERIFY は、効果が見込める箇所、つまり HIGH が見つかったサイクルで、新しいコンテキストから一度再確認することで、このギャップを埋めます。

実行条件。 このサイクルの ALIGN で HIGH の指摘が 1 件以上あった場合に限り、VERIFY を実行します。それ以外の場合はスキップし、その旨を align.md に記録します。MEDIUM または LOW の指摘、あるいは lint ERROR は実行条件になりません。実際の 47 回の実行で測定したところ、この条件では新しい問題が見つかったはずの実行も一部スキップされますが、WALKTHROUGH が補完します。実際に見落としが発生する場合は、実行条件を広げてください。

1. 上記の ALIGN パスの記憶を持たないサブエージェントを起動します。受け取るのは、現時点の成果物（修正後）と、このスキルの ALIGN ステップ 2 のチェックリストだけです。ALIGN が作成した整合性マップ、指摘、解決内容は受け取りません。
2. 同じ 5 つの観点（および該当する場合は引き継がれた WALKTHROUGH 項目）について独自の整合性マップを作成し、次の内容を報告します。ALIGN のマップが見落とした HIGH（ALIGN が LOW に分類したものの、新たに確認すれば HIGH または MEDIUM と判断される、ゲートが見落とした結果を含む）と、ALIGN が適用した各機械的修正が実際に正しいと確認できるか（修正が成果物の現状の要件に合致しているか）、それとも誤りが残っているか不完全かを報告します。
3. VERIFY で新しい問題が見つからなかった場合は、WALKTHROUGH に進みます。
4. VERIFY で ALIGN が見落とした HIGH、または問題を実際に解決していない機械的修正が見つかった場合は、それをこのサイクルのマップに追加します（ALIGN の指摘と同様に align.md に追記します）。その後、ALIGN ステップ 8 のルールに従って解決し（機械的修正は直接適用し、HIGH の判断が必要なものは個別に回答を求めます）、WALKTHROUGH に進みます。同じサイクル内で VERIFY を再実行しないでください。2 回目の見落としは、WALKTHROUGH で再度取り上げられた場合、次のサイクルの VERIFY で検出します。
5. 現在の環境でサブエージェントを起動できない場合は、VERIFY を実行できなかったことを明示し、VERIFY なしで WALKTHROUGH に進めてよいかユーザーに確認します。このステップを黙ってスキップしないでください。

ウォークスルー

ALIGN と VERIFY では、成果物同士の整合性を検証します。どちらも、人間がそれらに目を通したかどうかは検証しません。エージェント以外の誰も内容を確認していない場合でも、どちらも提示すべき点はないと判断することがあります。VERIFY の完了後（またはスキップ後）に、毎サイクル、初回も含めて、ALIGN と VERIFY で何も見つからなかった場合でも、必ず WALKTHROUGH を実施してください。

1 ラウンドにつき質問は 1 つです。レビュー担当者が読む順に進めます。

1. 1 ページの要約を次の順で表示します。
   • 仕様： 機能ごとに 1 行で、必要な内容とシナリオ数を示します。
   • 設計： Decisions の見出し、Risks / Trade-offs の脅威に関する行、Shape / Seams の名称を示します。実際のシームが記載されている場合（「no new code surface」ではない場合）は、そのセクション自体を読むようユーザーに依頼してください。シームは実装が基づくテスト境界であり、振る舞いではなくシグネチャとして読めるため、誤ったシームは読み飛ばされやすいからです。
   • カバレッジ表： シナリオごとに 1 行とし、scenario -> task group（tasks.md の Covers: から） -> seam（design.md の Shape / Seams から）の順に示します。lint がすでに確認したリンクから作成してください。シナリオに対応するシームがない場合は「no seam」と表示します。この点はすでに指摘事項として挙げられています。
   • タスクと提案： それぞれ 1 行で、ファイル名のみを示します。レビュー担当者が最初に読む仕様と設計の後に置かれています。
   • 規模の事実： lint の Size facts: 行を、事実のみとして示します（機能、シナリオ、タスクグループ）。評価は加えません。
2. 要約全体を対象とする一般的な質問を 1 つだけします。これらのファイルについてユーザーが変更したい点があるかを尋ねます。「はい／いいえ」での確認ではありません。「特になし」という回答も有効です。この質問では、必ず plain-language-writing スキルの COMMS ルールに従ってください。
3. align.md の Walkthrough log にラウンドを記録します。表示したファイルにサイクル番号のタグを付け、ユーザーの回答を一字一句そのまま記録します（「特になし」という回答も含みます）。

ユーザーが何も言わなかったことや、会話中の別の質問への回答から、ラウンドが完了したと推測してはいけません。要約全体を対象とする回答を個別に記録して、初めてラウンドは完了します。

ループの終了

WALKTHROUGH のラウンドが完了した後（そのラウンドの質問に回答があった後）、次のように判断します。

• 問題なしのラウンド： 回答が「特になし」だった場合、ループを終了します。適用に進みます。
• フィードバックあり： 回答に何らかの指摘があった場合、新しいサイクルを開始します。そのフィードバックを次の ALIGN の整合性マップ（ステップ 2）に反映し、他の指摘事項と同様に解決します（HIGH/MEDIUM/LOW、MECHANICAL/DECISION）。その後、新しいラウンドで WALKTHROUGH を再度実施します。
• ユーザーが早期に承認： ユーザーは、成果物の準備が整っており、これ以上サイクルを繰り返す必要はないと明示できます。これは、WALKTHROUGH のラウンドを少なくとも 1 回完了した後にのみ有効です。初回のウォークスルーに代わるものではなく、実際に 1 回実施した後にのみループを終了できます。承認（サイクル番号、ユーザーの発言）を align.md に記録して終了します。
• 3 サイクルに到達： ループが終了しないまま 3 サイクル目が完了した後、続行するか承認するかをユーザーに尋ねます（この場合も WALKTHROUGH の承認は有効です）。回答を記録します。これはチェックポイントであり、上限ではありません。ユーザーが続行を希望する場合、ループを続けます。

これら以外の理由で適用に進んではいけません。ALIGN だけで進むことも、ウォークスルーが未完了の状態で進むことも、ユーザーが何も言わなかった状態で進むこともできません。