qa-gate

QA ゲート

公開インターフェースを通じて、実際のユーザーが利用する方法で機能を実行し、その仕様で約束された内容に照らして組み立て済みの機能を検証します。Daemon は、_tasks.md のフロントマターで指定された、作成者が定義した唯一の終端 qa Task からこのスキルを実行します。このノードは Task Graph の一部であり、実行ごとのリクエストではありません。このノードは QA 以外のすべてのリーフに依存しているため、閉じる対象のグラフが確定した後にのみ実行可能になります。このスキルがゲート全体（計画、実行、証拠、指摘事項、レポート、最終判定）を担います。エージェントのツールと接続済みサーバーを直接使用してください。別の QA スキルを読み込んだり、独立した継続的な QA ツリーを作成したりしないでください。

必須事項

1. 実際のユーザーと同じ立場で検証する。 想定される利用者と同じフロントエンド、API、CLI、データワークフロー、または文書化された運用経路から操作してください。内部ヘルパーやコードの調査は失敗原因の診断には使えますが、ユーザーストーリーの合格を証明することはできません。
2. 楽観的な状態に頼らず証明する。 合格には、期待される観測結果、再読み込みまたは別の公開読み取り経路による独立した確認、該当する場合はリフレッシュや再起動後も維持されること、そして取得済みの証拠が必要です。
3. 再開可能な証拠を残す。 最初の確認を行う前に、すべての行を pending にした日付入りレポートを作成してください。各行の確認後にレポートを更新し、中断した実行を完了済みの作業を繰り返すのではなく、ディスク上の状態から再開できるようにします。
4. 判定は正直に一つだけ示す。 初期状態のレポートは pending です。初期状態のフロントマターをそのレポート唯一のフロントマターとして保持し、そのブロックと Results の行を埋めてください。計画した各行は最終的に pass、fail、blocked、skipped のいずれかになり、レポートを閉じる時点で pending の行はゼロでなければなりません。QA の行を一つも記録していないレポートではゲートは確定しません。フロントマターが空、または重複しているレポートでもゲートは確定しません。
5. ブロック理由を種別ごとに記録する。 確認済みの環境要因により到達できない行は blocked (environment: <cause>) として記録し、rows_blocked_environment に加算してください。指摘事項により中断された行は blocked (finding: <id> — waits on <named failure>) として記録し、rows_blocked_finding に加算してください。実行前の Spec に該当する宣言があり、その理由で到達できない行は blocked (declared: <criterion>) として記録し、rows_blocked_declared に加算してください。この3種類の理由は分けてください。レポートや判定を見栄えよくするために、別の理由にまとめてはいけません。
6. バイナリの識別情報。 監査者に関するフィールドは Daemon が管理します。初期状態の auditing_binary と auditor_staleness の行は変更しないでください。公開 CLI の各行を実行したバイナリの --version の出力を user_flow_binary として記録します。Roundfix の自己監査では、監査対象の Run Worktree で make build を実行してそのバイナリをビルドし、公開 CLI の行には ./bin/roundfix のみを使用してください。PATH 上で見つかった roundfix は決して使用しないでください。

実行可能な証拠

実行可能な証拠は .go.txt のようなコンパイル対象外の拡張子で保存してください。リポジトリのゲートでコンパイルまたはフォーマットされるソースファイルとして保存してはいけません。後続の実行では、インポート時にコンパイル対象のソースをスキップし、スキップした各パスを記録します。

QA の決着

同じ結果によって、作成済みの qa Task を決着させ、アーカイブ可能な対象が決まります。

結果	決着内容	アーカイブ対象
pass	許可されないブロック行がレポートにない場合、QA Task を completed として決着させ、Spec をアーカイブ可能にします。	Spec と、その QA レポートおよび証拠。
条件を満たす宣言済みの partial	事前の Pull Request 行以外の未達行すべてが、一致する ## Unreachable Acceptance 宣言でカバーされている場合、QA Task を completed として決着させます。blocked (environment: no open Pull Request) として記録され、根拠情報で Pull Request 行が明示されている事前の Pull Request 行は、条件を満たす partial の判定要因にはならず、Unreachable Acceptance 宣言も不要です。	Spec、その QA レポートおよび証拠、ならびに宣言の satisfied-by 記録。
environment-blocked	行はブロックされたままです。同等の証拠が環境ポリシーを満たす場合、レポートは pass として決着できます。	それ自体では何もありません。条件を満たすレポートがあれば、Spec をアーカイブできます。
failed	QA Task は未解決のままとなり、承認済みのオーバーライドが適用されない限り、アーカイブを拒否します。	なし。
missing	QA Task は未解決のままとなり、承認済みのオーバーライドが適用されない限り、アーカイブを拒否します。	なし。
override	QA Task のステータスもレポートの判定結果も変更せず、QA が失敗または欠落していても、明示的に承認されたものとしてアーカイブを決着させます。	qa_override、qa_override_approval、qa_override_reason、qa_override_qa_outcome、QA Task が未完了の場合は qa_override_qa_task_status、および qa_override_revision を伴う Spec。QA ファイルはバイト単位で同一のまま移動します。

1. スコープと前提条件を確認する

docs/specs/<slug>/ を特定し、_tasks.md、_prd.md、すべての task_NN.md、および qa/ 配下の過去のファイルを読みます。マニフェストの qa: フィールドが現在の type: qa Task を指定していること、またこのノードが終端であり、 QA 以外のすべてのリーフノードに依存していることを確認します。作成済みノードがない、または一致しない場合はグラフの欠陥です。そのノード以外でゲートを実行してはいけません。

ゲートで Surface Transcript を検証する

TechSpec で指定された Surface Transcript ごとに、QA マトリクスに 1 行を追加します。 その行では、ビルド済み製品を通じてトランスクリプトのコマンドを再実行し、TechSpec の一致ルールに従って標準出力、標準エラー出力、終了コードを比較します。1 行の ... は連続する 0 行以上に一致し、山括弧内のテキストは同じ行内の 1 文字以上に一致し、それ以外はすべて完全一致です。標準出力と標準エラー出力は別々に比較し、終了コードは常に完全一致させます。その行の根拠情報にトランスクリプト名を記載し、観測された出力を証拠として保持します。

• クリーンな作成チェックはゲートの前提条件であり、ゲートの代替ではありません。アクティブでレガシーではない Spec ごとに、次を実行します。

  roundfix spec check <slug> --strict
  

  このゲートでは、プローブなしの形式を維持します。プローブは作業が存在する前にコマンドがすでに成功するかを確認する一方、ゲートはすべての Task が完了した後に実行されるためです。したがって、完了済みの Task に対してプローブを実行すると、すでに成功しているコマンドが無意味なものとして報告され、ゲートが拒否されます。3 つの作成スキルでは、答えを確認できる作成中に --run-verification を使用します。

  コマンドが失敗した場合は、マトリクスの作成を始める前に停止し、停止する前に拒否の記録を書きます。この時点で停止したゲートは要件を一つも測定していないため、レポート全体を拒否の記録とします。

  ---
  verdict: fail
  rows_blocked_precondition: 1
  auditing_binary: "<version-and-build-identity>"
  auditor_staleness: "<state>: <reason>"
  rows_blocked_environment: 0
  rows_blocked_finding: 0
  rows_blocked_declared: 0
  precondition_check: "roundfix spec check <slug> --strict"
  precondition_reason: "<every refusing code and the sentence beside it>"
  ---
  
  # QA Report
  
  ## Results
  
  | # | Status | Provenance |
  | - | --- | --- |
  | 0 | blocked | precondition |
  
  ## Precondition refusal
  
  - check: roundfix spec check <slug> --strict
  - reason: <every refusing code and the sentence beside it>
  

  0 行は行列全体を表します。何も実行されていないため blocked、停止理由が測定結果ではなく拒否であるため、来歴は precondition です。拒否された SC-* コードをすべて precondition_reason に記載し、コードを先に、その後に説明文を続けて、 ; でつなぎ、1 行にまとめます。これにより、レポートを読むメンテナーは Spec とツリーのどちらを修正すべきか判断できます。 行の根拠は、## Results の下に 2 つ目のテーブルを作るのではなく、必ずリストとして文章で記述します。Results テーブルを空にするのは 選択肢ではありません。空の Results テーブルでは、Spec ではなくこのレポートに基づいて後続の実行をすべて拒否することになり、 指定された修正である、計画済みのすべての行を実体化する作業は、行列を一度も構築していない実行では行えません。

  ここで停止したゲートは、それ以外には何も書き込みません。行列も、実行されなかったチェックの行も作成しません。

  コマンドが成功した場合は、レポートのスコープと環境にクリーンな結果を記録します。ただし、以下の表にある作成ルールを繰り返す QA 行列の行を作成してはいけません。完了済みまたはアーカイブ済みのレガシー Spec は、制約の強制的な補完の対象外です。レガシー成果物は すべてバイト単位で同一に保ち、置き換えるクリーンな作成結果のないガバナンス行は残します。Project Constraints セクションがないことだけでは、 レガシーである証明にはなりません。

QA 行列から削除された作成ルール	spec check 相当のルール
作成された Task Graph が解析され、PRD の約束が Task に対応付けられ、宣言されたリポジトリパスが解決される。	SC-COVERAGE-UNTASKED が必要とする Task Graph の読み込みに加え、SC-COVERAGE-UNTASKED と SC-REF-UNRESOLVED
PRD の約束が TechSpec に対応付けられる。	SC-COVERAGE-UNMAPPED
必須の Project Constraint 行がすべて存在する。	SC-CONSTRAINT-MISSING
宣言された Project Constraint の適用性に理由がある。	SC-CONSTRAINT-UNREASONED
Project Constraint 行が有効なソースを引用している。	SC-CONSTRAINT-SOURCE
引用されたツール使用許可に Spec が記載されている。	SC-TOOLING-UNAUTHORIZED
適用対象のツール権限に、対象範囲を限定したファイルが宣言されている。	SC-TOOLING-UNBOUNDED
ツール使用許可の記録に、許可内容が読み取り可能なフィールドで記載されている。	SC-TOOLING-UNTYPED
保留中の非 QA Task で宣言された Governed Path がすべて使用許可の記録と、存在する各 Tooling 権限行に記載されている。	SC-TOOLING-UNDECLARED
CLI サーフェスを指定する保留中の非 QA Task にはすべて、その Task または推移的な依存関係にガイドが指定されている。	SC-CLI-UNDOCUMENTED
有効な ADR の義務が列挙され、関連する決定が考慮され、出典を明記した主張が引用された記録と一致している。	SC-ADR-UNLISTED、SC-ADR-RELATED、SC-CITATION-UNSUPPORTED
Task の要件が互いに矛盾せず、リハーサルが宣言され、Verification によって Task の作業と未実施を区別できる。	SC-REQUIREMENT-CONTRADICTORY、SC-REHEARSAL-UNDECLARED、SC-VERIFY-WORK-INDEPENDENT
出力される語彙が TechSpec の Vocabulary Contract で文書化されている。	SC-VOCABULARY-UNDOCUMENTED
リポジトリのループ宣言と Finding、Rollup、アーカイブ、昇格した Backlog のライフサイクルが一致している。	SC-LOOP-ORDER-DIVERGENT、SC-FINDING-LIFECYCLE、SC-ROLLUP-MEMBER、SC-ARCHIVE-LICENSE、SC-BACKLOG-UNMOVED

チェッカーのスキップ一覧に記載された名前付き検出器は実行されていません。それは相当するルールではないため、対応する QA 行を残します。 類推によってこの対応表を拡張してはいけません。チェッカーが解析しなかった適用性、ツール使用許可の欠落、外部の証拠、 Non-Goals、レポートの契約、現在の Task ステータス、ライブ制御または時系列の動作は、名前付きのチェッカールールが判定する場合を除き、 ゲートの対象として残します。

• コミットに依存するツール監査は、マトリクスの行として維持します。リポジトリのツール設定、スクリプト、無視ファイル、プラグイン宣言、またはバージョン固定を実際に作成、編集、名前変更、移動、削除するすべての Task を特定します。機械的なステージでは、デリバリーベースから監査対象の HEAD までのすべての Task コミットを監査し、認可監査テーブルには監査した各コミットを記載します。この範囲内にある Task コミットのうち、テーブルに記載されておらず、リポジトリのツール関連パスを変更しているものに限り、コマンドによる監査を行います。レポートの機械的なスキップに Task commits of earlier Runs と記載されている場合は、コマンドですべての Task コミットを監査します。各コマンド行は、Daemon が所有する Task コミットの実際のパスと、現在のワークツリーの差分に対して実行し、認可、前提修正、後続修正のコミットを時系列の祖先関係に沿って特定します。報告されたファイル一覧を信頼せず、コミットされた変更ごとに git diff-tree --no-commit-id --name-only -r <commit> を使います。
• コミット後に判明した認可形式の問題はすべて、同じ失敗したコマンド行にまとめて報告します。対象は、認可の欠落、遅延、または追跡不能、認可または前提修正が Task コミットに取り込まれていること、後続修正が原因となった変更に取り込まれているか、その変更より前に並んでいること、認められた再生成コマンドによる再現可能な証拠のない派生バージョン固定の申告、および正確に限定されたリストと割り当てられた Task ファイル以外のすべてのパスです。最初の問題で止めて、残りを別の QA 再実行に先送りしてはいけません。マトリクスが作成された後は、検出事項によってブロックされるのは、その検出事項に依存する行だけです。
• QA はレポートと証拠のみを書き込みます。Task のステータスや Task Graph の依存関係は変更しません。
• 作成者が定義した qa Task のすべての依存関係が completed であることを必須とします。未完了の依存関係がある場合は停止し、それらを列挙します。現在のゲート Task のステータスは Daemon が所有し、最終判定に基づいて確定します。部分ゲートを実行できるのは、作成者が定義した QA Task がスコープを明示的に限定している場合のみです。その場合、スコープと最終判定を partial とします。マトリクスができる前に Agent Session を保留する機械的ステージの動作は変わりません。ブロック要因となる機械的事実がある場合、マトリクスの作成前にゲートを停止します。マトリクスを宣言した場合は完全なゲートであり、pass に到達できます。マトリクスを宣言しても実行が部分的になるわけではありません。partial は、スコープを明示的に限定した qa Task、またはゲートが実行しなかった計画済みの行にのみ使用します。
• PRD で宣言されたサーフェス、ユーザーストーリー、コア機能、受け入れ基準、ユーザーエクスペリエンスの状態、Non-Goals を特定します。
• 実行前に、PRD の ## Unreachable Acceptance セクションにあるすべての項目を読みます。各宣言は検証対象の作成者による主張として扱い、証拠としても、その行を省略する許可としても扱いません。ゲートは、ブロックされた行をこれらの実行前宣言のいずれかにのみ紐付けられます。到達不能であるとゲート自身が宣言したり、失敗した試行から宣言を推測したりしてはいけません。
• 各 Task の ## Result を読みます。Task レベルの基準を達成として扱うのは、名前が示された再現可能な証拠を参照し、それが依存する静的チェックに合格している場合に限ります。無関係な静的チェックの失敗は、その証拠を無効にしません。ライブ QA の労力は、組み立てられたユーザージャーニー、タスク間の接続部分、永続性、失敗時の動作、スコープの逸脱に充てます。
• 再実行時は、Daemon が carried (established by: …; head: …) として設定したすべての行を維持します。これらは合格として扱い、再実行しません。それ以外のすべての行を実行し、シードされた ## Row carry-forward セクションに re-run と記載された行から開始します。

対象範囲は、網羅性が満たされ、閉じられたときに完了します。

Requirement が Task の変更ファイルを宣言と照合して監査する場合、Task ファイルの ## Recorded paths に記載されたパスは宣言済みとして扱い、その行に明記します。Governed Path には引き続き認可が必要です。

2. QA マトリクスを作成し、レポートを開く

実行前に、衝突しないレポートパスを作成します： その日の最初のレポートには docs/specs/<slug>/qa/qa-report-YYYY-MM-DD.md を使用し、同じ日に再実行する場合は、同じ日付の既存サフィックスの最大値より 1 大きいサフィックスを付けた qa-report-YYYY-MM-DD-NN.md を使用します。前の番号に空きがあっても埋めません。同じ日に使用できるサフィックスは数値のみです。スコープやビルドのスラッグは使用しません。既存の status: in-progress レポートを再開できるのは、同じビルドのレポートである場合に限ります。それ以外の場合は次の番号のレポートを新規作成し、古いレポートは履歴として保持します。

Pull Request のジャーニーを計画する前に、Roundfix QA プロンプトにある Pull Request の事実を確認します：

Pull Request の行では、デフォルトで同等の証拠を用いる方法を取ります。ADR-0088 に基づき、Open Pull Request が存在する前に作成者によるゲートが実行されるため、Specs はその状況を再確認するために時間を費やしてはいけません。その行をマトリクスに残し、Pull Request が検証するはずだった各コントロールについて、行の環境要因とともに、観測した、または監督下で得た同等の証拠を記録します：

• 承認 — 変更を承認した人、または承認が得られなかったこと；
• チェックとステータス — リポジトリの Verification と必須チェックをローカルで実行した結果；
• 未解決のレビュー スレッド — 該当するものがないこと、または未解決のスレッド；
• Merge-Ready の受け入れ — 期待されるヘッドに対する Review Source の証拠、またはまだ存在しないこと；
• レビュー成果物の系譜 — 証拠が属するヘッドと、それが行で対象としているヘッドであること；

この行を黙って合格扱いにしたり、省略したりしてはいけません。同等の証拠がないコントロールがあれば、その行はブロック状態のままです。ADR-0080 は証拠のないジャーニーを認めず、列挙されたコントロールに回答しないことは、まさにそれに該当します。

• 事実に Open Pull Request があると記載されている場合、そのジャーニーは実行可能です。既存の gh と Review Source の境界を通じて、その Pull Request を読み取り専用で確認します。必要に応じて、承認、チェックとステータスの証拠、未解決のレビュー スレッド、Merge-Ready の受け入れ、および Daemon のレビュー成果物の個別のコミット系譜を確認します。Pull Request の変更、スレッドの解決、コミット、プッシュは絶対に行わないでください。
• 事実に Open Pull Request がないと記載されている場合、すべての Pull Request ジャーニーを blocked (environment: no open Pull Request) と記録し、rows_blocked_environment に含めます。PR 前の Pull Request の行によって、条件を満たす部分的な結果が決まることはなく、Unreachable Acceptance の宣言も必要ありません。その出所には Pull Request の行を明記します。Pull Request を解決できなかったと事実に記載されている場合、その不在は証明されていません。原因を blocked (environment: Pull Request unresolved) と記録し、確認済みの不在として記述してはいけません。Run Worktree ブランチから Pull Request を解決しようとしてはいけません。この Run ごとのブランチはプッシュされず、独自の Pull Request も持たないためです。

カバレッジのソース

MUST verify または MUST run で始まる番号付きの各 qa タスク要件は、宣言された検証要件です。それ以外の要件は、ゲートの実行方法を制約します。

qa タスクに宣言された検証要件が少なくとも1つある場合、それらの要件がマトリクスのカバレッジソースを定めます。名前が挙げられたタスクのすべての受け入れ基準を検証する宣言済み要件では、その基準のそれぞれが個別のソースになります。

宣言の有無にかかわらず、すべてのマトリクスは、以下の免除不可のソースをカバーします。

• 外部証拠の行。
• 同等の証拠を用いる経路でのプルリクエストの行。
• リポジトリの検証。
• PRD の ## Unreachable Acceptance セクションにある各宣言。
• frontend が宣言されている場合のフロントエンドの一斉確認。

宣言された検証要件がない qa タスクには、範囲を限定したデフォルトを適用します。 そのカバレッジソースは以下のとおりです。

• PRD のユーザーストーリーと目標。
• QA 以外の各タスクの受け入れ基準。
• 宣言された意図的な破損箇所。
• 上記の免除不可のソース。

非目標がソースになるのは、Spec でリリース可能な可視の対象を指定している場合だけです。その行では、Spec が変更した経路と、非目標が指定するサーフェスのみを確認します。

カバレッジと出所

カバレッジは完全で、閉じており、名前が明示されています。

• すべての行の出所には、その行がカバーする各カバレッジソースを記載します。
• すべてのカバレッジソースが、少なくとも1つの行の出所に記載されます。
• どの行の出所にも、カバレッジソース以外のソースを記載しません。
• 1つの観察で結論を出せる複数のソースは、1つの行にまとめてもかまいません。
• 行の結果を、他の行の結果から算出してはいけません。
• どの行でも、機械的な拒否コードを再確認してはいけません。

各行には、カバーするソース、アクター、エントリーポイント、サーフェス、手順、期待される可視の結果、独立した確認方法、永続化の確認、証拠のパス、pending ステータスを出所として記録します。行はユーザーへの影響と影響範囲の大きさの順に並べます。リスクの高いジャーニーに対する動作プローブは、範囲を限定したデフォルトにのみ含めます。そのデフォルトに含まれるリスクの高い各ジャーニーについて、関連するプローブを2～5個選択します。二重送信、操作の途中での更新または戻るナビゲーション、ディープリンクや再オープン、無効な入力または順序どおりでない入力、セッションの期限切れ、オフラインからの再接続、複数のタブでの同時操作、ロケールやアクセシビリティの変更などです。機能に適したプローブを選択します。無関係なプローブはノイズを生みます。 出所には、Requirement 3、Task 01 criterion 2、repository Verification など、qa タスク自体の識別子を使用します。

行入力の宣言

エージェントが実行するすべての行は、詳細なエビデンスブロック内で、空でない型付きの inputs: リストを宣言します。その行の入力は、pending として計画された時点で固定され、その行が読み取る内容の範囲に限定されます。### <row-id> 見出しの下にブロックを配置してください。行識別子は Results テーブルの # セルと一致させ、行ごとにフェンス付きの yaml ブロックを1つ使用してください。それ以外の見出しの下にあるブロックは無視され、その行は引き継がれません。各項目には kind と ref があります。

inputs:
  - kind: repository_path
    ref: <repository-relative path or glob>

その行の真偽が依存する入力ごとに、項目を1つ使用してください。

種類	使用する場合
repository_path	エビデンスが、現在のリポジトリ内のリテラルパスまたは glob にある内容に依存する場合。
external_repository	エビデンスが別のリポジトリ内の内容または状態に依存する場合。その行は引き継ぎできません。
live_service	エビデンスが稼働中のサービスから観測された状態に依存する場合。その行は引き継ぎできません。
elapsed_time	エビデンスが経過時間、経過年数、期間、または時間枠に依存する場合。その行は引き継ぎできません。
commit_range	その行が Task のコミット、その認可、または変更されたファイルの範囲を読み取る場合。その行は引き継ぎできません。

保守的に宣言してください。ビルド済みバイナリがコンパイル元とするすべてのソースや、モジュールマニフェストを含め、その行が読み取るすべてのソースを含めます。該当する種類はすべて宣言してください。リポジトリ以外の入力が1つでも含まれるリストは引き継ぎできません。inputs: の宣言がない行、またはリストが空の行は実行に無効であり、再観測が必要です。そのため、引き継ぎはオプトインであり、フェイルクローズのまま維持されます。

inputs: のないレポートは、これまでとまったく同じように扱われます。既存の行、件数、ステータス、判定ルール、レポート名は変更されません。将来のラウンドが終了したとき、リポジトリ入力のみを宣言し、その系譜が証明され、後のヘッドでエビデンスがバイト単位で同一である pass 行は、carried (established by: <report>; head: <sha>) として記録され、再観測されません。

実行後に入力が増えた行は、引き継ぎできません。引き継ぎの対象にするために、実行後に入力を追加しないでください。

行が inputs: を宣言する前に書かれたレポートを対象にゲートを再開した場合、そのレポートに記録された inputs: のない行はすべて再実行されます。そのような行は引き継ぎできません。新しいパスで再実行される行は、そのパスで pending として計画される時点で入力を宣言します。これは独自の入力を持つ新たな観測であり、実行後に入力を追加することではありません。以前のレポートの行に inputs: を追加してはいけません。

エージェントは evidence_snapshots を書き込みません。デーモンがターンの後に記録します。リポジトリの Verification または Pull Request の行を指す行は、常に観測されます。また、commit_range を宣言する行も常に観測されます。

1つの行は、Spec の外部エビデンス行です。つまり、Spec 自身の成果物の外部に由来するエビデンスに基づく受け入れ行です。たとえば、Spec が構築していないリポジトリ、Spec が設計していない測定、公開済みの文献などです。そのエビデンスの出所を、後の読者が同じ出所にたどり着けるだけの精度でその行に記録してください。これにより、その結果が Spec 自身の前提の予行演習として読まれることを防ぎます。その出所を入手できない場合は、到達できなかった理由を記録し、行を blocked (environment: <cause>) として記録して、rows_blocked_environment に含めてください。その行を削除してはならず、Spec が作成したエビデンスで満たしてはなりません。ブロック中または部分的な外部エビデンス行がある場合、その行が満たされるか、ADR-0097 に基づき宣言済みの変更されていないエビデンスを使って引き継がれるまで、プルリクエストの準備はブロックされます。Task の作成はそこで停止しません。分解時にブロック中の行を記録して続行するため、この義務はここ、つまり Spec に説明が求められるゲートの段階で生じます。ADR-0104 を参照してください。

すべてのカバレッジソースが少なくとも1つの行の来歴に含まれ、どの行の来歴にもカバレッジソース外のソースが含まれず、選択されたすべてのデフォルトプローブに理由があり、レポートに保留中のマトリックス全体が含まれている場合、計画は完了です。

3. 静的ゲートを最初に実行する

Daemon 割り当てのゲートでは、Daemon がすでにリポジトリの検証を実行し、その結果をプロンプトで提示しています。その結果を記録し、リポジトリの検証を再度実行しないでください。単独のゲートでは、リポジトリで選択されている検証を実行してください。選択されている検証をまったく実行できない場合は、検証ゲートをブロックとして記録してください。実行されたフォーマット、テスト、またはビルドのチェックが失敗した場合、それはブロックではなく fail です。何かを記録する前に、以下のコード起因と環境起因の区別に従って分類してください。

リポジトリの検証でタイムアウトや断続的な失敗が発生した場合、環境ブロックではなく、 失敗として記録します。競合の主張、再現できない実行、または変更されていない納品対象で同じ失敗が発生したことは、環境起因の原因が証明されたことにはなりません。環境起因とみなせるのは、コマンドを まったく実行できなくする原因だけです。

qa タスクでリポジトリの検証以外のアナライザーが指定されている場合は、 変更されたパッケージに対して実行してください。納品対象でも同一の診断が発生する場合は、それを所有する Spec を明記して、観測された事象として記録し、Spec の失敗とはしません。 リポジトリの検証の失敗は、既存のものかどうかにかかわらず、引き続きブロッキング要因となります。

コマンドが失敗した場合は、続行する前に原因を診断してください。

• コード起因： マトリクスが作成された後は、検出事項によってブロックされるのは、それに依存する行だけです。検出事項を記録し、失敗したチェックを、その失敗した内容に依存するエントリーポイント、観測可能な項目、または証拠を持つマトリクスの行まで追跡します。影響を受ける行だけを blocked (finding: <id> — waits on <named failing check>) としてブロックし、結果の有効性が保たれる、影響を受けない行はすべて続行してください。ビルドの失敗によって実行可能な成果物が残らない場合など、すべての行が実際に依存している場合に限り、失敗によってマトリクス全体をブロックできます。その場合も、マトリクス全体について一度だけ主張するのではなく、各行にその依存関係を記録してください。
• 環境起因： リポジトリの検証以外のチェックでは、エラーまたは変更されていないベースでの再現によって制約を証明し、影響を受ける行を blocked (environment: <cause>) として記録してください。有効なチェックは続行し、セクション 6 の型付きブロック原因に関する判定ルールを適用してください。

静的ゲートは、合格するか、すべての失敗が分類され、影響を受けるすべての行に待機対象のチェックが明記され、環境起因のブロックすべてに具体的な証拠と明示的な解除要件があり、残りの行が安全に実行できるものとして特定された時点で完了です。

4. 実際のフローを実行する

本番に近いエントリーポイントからアプリケーションを起動します。ビルドまたはコミット、コマンド、URL またはバイナリ、データのセットアップ、認証情報プロファイル、すべての同等性の逸脱を記録します。

マトリックスの各行について、次のループを繰り返します。

1. 実際のエントリーポイントから、指定されたアクターとして入ります。
2. 公開されたインターフェイスを通じて操作し、製品がユーザーに表示する応答を確認します。
3. 再読み込み、再起動、ディープリンク、2 つ目の公開エンドポイント／コマンド、または別のユーザー可視の読み取り経路で結果を確認します。
4. 目標状態とすべての逸脱について証拠を取得します。スクリーンショットと焦点を絞った成果物を qa/evidence/<YYYY-MM-DD>-<run-slug>/ に保存し、正確なコマンドと簡潔な出力をレポートに記載します。
5. 行をただちに更新します。進行停止、操作できないコントロール、無限スピナー、または消失した状態は、製品を回避する理由ではなく、指摘事項です。

行が期待される可観測状態に到達できない場合は、その行と、立証された原因を実行前の宣言と照合します。その行が宣言された基準に一致し、観測された制約も宣言の理由と一致する場合に限り、blocked (declared: <criterion>) を使用します。それ以外の状況は、実際の原因に応じて環境によるブロック、または指摘事項によるブロックとします。一致する宣言がないブロック行は、既存の原因を維持し、既存の判定ルールに基づいてブロック状態のままとします。

ゲートが宣言された行に到達できる場合は、通常どおり実行し、宣言を誤って宣言された行に関する指摘事項として報告します。フローが成功したという理由だけで、その宣言を受け入れたり、無視したり、削除したりしてはいけません。到達可能なフローは Spec の主張が誤りだったことを示す証拠であり、その指摘事項がある限り pass にはなりません。

サーフェスプロトコル

サーフェス	実施内容	最低限の証拠
frontend	実際のブラウザーを操作し、各アクターのフローを実行します。ナビゲーションまたは DOM の変更後に、インタラクティブな状態を再確認します。	重要な状態と失敗のスクリーンショット、更新／ディープリンク後の独立した確認、コンソールエラー／警告、失敗したネットワークリクエスト。
backend	名前が指定された失敗モードを含め、稼働中の文書化された API に実際のリクエストを送信します。	正確なリクエスト、ステータス、ペイロード、副作用を確認する公開読み取り。
cli	インストール済みまたはビルド済みのコマンドを、オペレーターが実行するのと同じ方法で実行します。	コマンド、終了コード、出力、状態を確認する 2 つ目のコマンド／読み取り。
data	実際のマイグレーションまたは同期をスクラッチデータベースに適用し、再実行します。	形状／行のチェック、区別の保持、副作用、冪等性の証拠。
infra	デプロイに合致する安全なスクラッチ／ドライラン経路を通じて適用または確認します。	コマンド出力、適用後の設定／状態、同等性の不足。
docs	文書化されていない知識に頼らず、想定読者としてドキュメントに従います。	試したコマンド、結果、不足している手順または誤解を招く手順。

フロントエンドの一通りの確認

frontend が宣言されている場合は、マトリクスで以下のすべてを確認します。

• ビューポートと入力： 名前付きブレークポイント、またはモバイル 375×812、タブレット 768×1024、デスクトップ 1440×900 を使用します。各サイズで主要なフローを完了し、画面の切り詰め、重なり、水平スクロール、キーボードのみでの操作、フォーカスの可視性、主要画面での 200％ズームを確認します。
• 状態と復旧： PRD の空、読み込み中、成功、検証、エラーの各状態を確認します。非同期アクションでは速やかにフィードバックを表示し、失敗時にも入力内容を保持し、復旧のための具体的な次の手順を提示します。
• アクセシビリティと言語： 入力項目とコントロールにアクセシブルな名前があり、見出しとフォーカスの順序に一貫性があり、色だけを唯一の手がかりとせず、画像に適切な代替情報があり、製品のコピーで仕様の用語を使用していることを確認します。
• ランタイムの健全性： 確認したフローで、説明のつかないコンソールエラーや警告、リクエストの失敗が発生しないことを確認します。利用可能な場合は、対象を絞ったアクセシビリティ監査または Lighthouse 監査を実行し、利用できない場合はその旨を明記します。

TUI の場合は、同じ確認を、大小および極端なサイズのターミナル、キーボード操作のフロー、フォーカスと追従の動作、色に依存しない読みやすさ、整列した出力、適切な割り込み処理に対応させます。

5. 結果と指摘事項を分類する

各行に、以下の終端ステータスを1つだけ割り当てます。

• pass：期待される観測結果、独立した確認、永続化の確認、証拠がすべてそろっている場合。
• fail：観測された製品の動作が仕様に反している場合、または非目標が実装されている場合。
• blocked (environment: <cause>)：ゲート環境によりジャーニーに到達できない場合。証拠、正確なブロック解除手順、利用可能な場合は同等の観測済みまたは監督下で得られた証拠を記載します。
• blocked (finding: <id> — waits on <named failure>)：期待される観測結果に至るのを指摘事項が妨げている場合。行が待つ対象となる失敗したチェックまたは動作を明記し、指摘事項と影響を受ける証拠へのリンクを付けます。
• blocked (declared: <criterion>)：対応する実行前の仕様宣言に記載された理由により行に到達できない場合。宣言へのリンク、ゲートが到達できなかった証拠、これを満たすために必要な人間による操作を記載します。
• skipped：明示的に部分的なゲート、またはリスクに基づく対象外の場合に限り使用できます。理由と未検証の内容を記載します。

各指摘事項をユーザーへの影響に基づいて分類します。

• Blocks-Completion：実行者が価値を提供するジャーニーを完了できません。
• Data-Loss：ユーザーデータが破壊、破損、または気付かれないまま破棄されます。
• Trust-Damage：矛盾した動作、アクセス不能な動作、または回復不能な動作により、信頼が損なわれます。
• Friction：回避可能な混乱、遅延、繰り返しを伴いながらも、ジャーニーは完了します。
• Cosmetic：完了や信頼に影響せず、表示が異なります。

すべての失敗について、実行者、ジャーニーの手順、期待される動作と実際の動作、公開エントリーポイントからの再現手順、証拠、影響度、影響を受ける行を記録します。指摘事項を新規として登録する前に過去の報告を検索し、症状が再発または退行した場合は、履歴を分割せず、その旨を記載します。

コードを修正する前に、予定した一通りの確認を完了します。ビルドを変更すると、以降の比較結果は無効になります。修正後は、新しい実行を開始するか、ビルドを明確にバージョン管理したうえで、静的ゲート、失敗したフロー、隣接するカナリアを再実行します。

6. レポートを完了する

次の構造を使用します。

---
spec: <slug>
date: YYYY-MM-DD
build: <audited-commit-or-artifact>
auditing_binary: "<version-and-build-identity>"
auditor_staleness: "<state>: <reason>" # state is current|stale|unknown; the reason names the signal that answered, such as commit ancestry or the declared tree version
user_flow_binary: "<the --version line of the binary that ran public-CLI rows>"
status: in-progress # in-progress | closed
verdict: pending # pending | pass | fail | partial
rows_blocked_environment: 0
rows_blocked_finding: 0
rows_blocked_declared: 0
surfaces: [frontend, backend]
---

# QA report — <feature>

## Scope and environment


## Static gate


## Results
| # | Status | Provenance |
| - | --- | --- |

For each row, put the story or criterion, actor, surface, steps, and evidence
in a block below the table.

## Findings


## Blocked and skipped


## Coverage


## Final verdict

status: closed として完了し、判定を機械的に適用します。

• いずれかの行が失敗した場合、またはゲートが誤って宣言された行を検出した場合は、fail。
• 失敗した行も誤った宣言もないものの、宣言によるブロック、検出結果によるブロック、またはスキップされた行がある場合、作成者が記述した QA タスクで部分実行が定義されている場合、あるいは環境によるブロック行に同等の観察済みまたは監督下の証拠がない場合は、partial。
• 実行可能なすべての行が合格し、環境によるブロック行にはそれぞれ原因と同等の観察済みまたは監督下の証拠が記録され、宣言によるブロック、検出結果によるブロック、またはスキップされた行がなく、誤った宣言もなく、すべての証拠パスが解決される場合は、pass。rows_blocked_environment が 0 以外でも、それだけでは pass の妨げにはなりません。rows_blocked_finding または rows_blocked_declared が 0 以外の場合は妨げになります。

rows_blocked_environment、rows_blocked_finding、rows_blocked_declared は、それぞれのブロック原因に該当する行の正確な数に設定します。いずれかの件数がゼロの場合も含め、完了したすべてのレポートで3つのキーを維持してください。

セクション1の前提条件による拒否行を含むレポートでは、provenance が precondition である blocked 行の正確な数を rows_blocked_precondition に設定し、さらに precondition_check と precondition_reason も含めます。ゲートがマトリックスに到達した場合は、これら3つのキーをいずれも記載しません。拒否は追加の形式であり、すべてのレポートに必要な4つ目の件数ではありません。

ゲートでは、QA の精算表で定義された条件を満たす宣言済みの partial、または pass の場合に、プルリクエストの準備が許可されます。それ以外の結果では、再実行前に何を変更または検証する必要があるかを記載します。デーモンが割り当てた Roundfix QA ステップでは、レポートを作成しますが、コミットやプッシュはしないでください。QA レポートのコミットはデーモンが行います。デーモンが割り当てたステップはサンドボックス内で実行される場合もあります。ワークスペース外の操作（$HOME への書き込み、ネットワーク、ネストされたツールの状態変更など）が権限エラーで失敗した場合は、直ちに環境が原因と分類し、該当する行を blocked (environment: <error>) として、処理を続行してください。サンドボックスの拒否を再試行し続けてはいけません。フルアクセスセッションが必要なチェックを環境レコードに記載してください。

判定例

• UI に「保存済み」と表示されても、更新後にレコードが消える場合：fail、Data-Loss。楽観的なメッセージは証拠になりません。
• スイート全体は合格するものの、実際の OAuth には人が管理するアカウントが必要で、同等の監督下の証拠がない場合：該当する行を blocked (environment: human-controlled account) とし、全体の判定は partial。人が行う正確な検証手順を記載します。
• Spec で実際のリリース公開は到達不能と宣言され、ゲートが、隔離された環境ではその取り消し不能な操作を実行できないことを証明した場合：該当する行を blocked (declared: publish the real release) とし、rows_blocked_declared を加算して、判定は partial。
• Spec でユーザージャーニーが到達不能と宣言されているものの、ゲートで実行できる場合：ジャーニーを実行し、誤って宣言された行として検出結果を記録して、ジャーニーのプロダクト動作に問題がなくても fail を返します。
• ガバナンスチェックが失敗しても、実行可能なアプリケーションの動作に影響しない場合：そのチェックを待つガバナンス行のみをブロックし、機能的なユーザージャーニーを続行します。
• 外部証拠の行に、この環境が保持していないリポジトリが指定されている場合：試行した検索を証拠として blocked (environment: <cause>) を記録し、rows_blocked_environment に加算します。Spec の作成者が用意したリハーサルで代用してはいけません。
• プロンプトでオープンプルリクエストが指定され、読み取り専用の観察によって承認、マージ可能であること、およびレビューファイルの系譜が確認できた場合：コミット、プッシュ、プルリクエストの変更権限なしで、そのプルリクエストに関するジャーニーを合格とします。
• タスクの Result に合格したユニットテストが記載され、組み立てられたブラウザジャーニーも更新後に永続化され、スクリーンショットがある場合：タスク基準を満たしたものとして認め、実際の証拠に基づいてユーザーストーリーの行を合格とします。

アンチパターン

• テスト、ソースコードの調査、ルートのレンダリング、または楽観的 UI だけを根拠に合格を宣言する。
• 実行後にのみレポートを作成し、再開可能性や未確認の行を失う。
• ハッピーパスが成功したことを理由に、失敗状態、動作の検証、またはレスポンシブ対応の確認を省略する。
• 目標状態や相違点ではなく、何百枚ものスクリーンショットを撮影する。
• 環境による拒否をコードの不具合として扱う、または原因の記録と同等の証拠なしに成功として扱う。
• 失敗を注記として曖昧にする、行を未処理のままにする、またはマトリックスの行なしにカバレッジを主張する。
• 一斉確認中に修正を加えながら、すべての行が同一のビルドで実行されたかのように続行する。