| name | cmate-acceptance-test |
| description | Issue の受入条件を自動検証と手動確認に分け、証跡付きで検証して Go / Conditional Go / No-Go を判定する。受入テスト、受入条件の検証、マージ可否・リリース可否の判断を求められたときに使う。 |
cmate-acceptance-test
対象 Issue の受入条件が満たされているかを証跡 (evidence) に基づいて検証し、
可否を go / conditional_go / no_go で返す手順である。
この Skill の出力は、versioned result document（schemas/acceptance-result.v1.json）と
human-readable summary の 2 つであり、どちらか一方だけを返して終了してはならない。
判定の中心にある規則は 1 つだけである。
検証していないものを pass に丸めない。
未実行・環境依存・flaky・blocked・手動未確認は、pass でも fail でもない固有の
outcome として記録し、判定に反映する。
0. 使う場面 / 使わない場面
使う場面:
- Issue の受入条件を満たしたかどうかを、証跡付きで確認したいとき。
- 実装が終わったあと、マージ・リリースの可否を第三者が再現できる形で残したいとき。
- 何が検証済みで、何が未検証のまま残っているかを分けて報告したいとき。
使わない場面:
- 実装や修正そのもの。この Skill は検証のみを行い、production code を変更しない。
- 失敗した test を通すための修正。原因調査と修正は別の手順に渡す。
- 受入条件が存在しない、または合意されていない Issue の可否判断。§4 Step 1 で停止する。
1. 入力
| 名前 | 必須 | 内容 | 欠けたときの動作 |
|---|
issue_ref | 必須 | Issue 番号または Issue URL | status: failure / verdict: no_go を出力して停止 |
target_ref | 必須 | 検証対象の worktree path、branch、commit | 利用者に問い合わせる。応答が得られなければ failure で停止 |
test_commands | 任意 | 実行してよい command と引数の一覧 | 自動検証を行わず、全 criterion を manual または not_run として扱う |
criteria_override | 任意 | Issue 本文の代わりに使う受入条件 | Issue 本文から抽出する |
evidence_dir | 任意 | evidence の保存先（既定 ./acceptance-evidence/） | 既定値を使う |
result_path | 任意 | result document の出力先（既定 ./acceptance-result.json） | 既定値を使う |
入力に関する強い制約:
target_ref は利用者が明示したものだけを使う。 現在の作業 directory、既存の
worktree、production の設定を「たぶんこれだろう」で対象にしない。- Issue 本文の取得は読み取りのみ。
gh issue edit などで Issue を書き換えない。
- 受入条件が Issue 本文から機械的に抽出できないときは、抽出結果を利用者に提示して
確認を取る。確認が取れない条件は
classification: not_verifiable として記録する。
2. 権限
この Skill が宣言する権限（commandmate.skill.yaml の declared_permissions）と、その用途:
| 権限 | 用途 | やらないこと |
|---|
filesystem_read | 対象 repository の source、test、設定の読み取り | 対象 repository の外の path を読まない |
filesystem_write | evidence_dir と result_path への書き込み、および §4 Step 3 で確認を得た test file の作成 | 既存 file の暗黙上書き。既存 file がある場合は必ず確認する |
process_execution | §3 の command 実行 | 宣言外 command の実行 |
network_access | Issue 本文の取得のみ | それ以外の外部送信。evidence を外部へ upload しない |
environment_read | 必要な環境変数が設定されているか否かの確認 | 値の読み出し、値の evidence への記録 |
declared_permissions は宣言であって強制ではない。この一覧を超える操作が必要になった
時点で、実行せずに利用者へ確認する。
3. 実行してよい command
Skill 自身が実行してよいのは、manifest の requirements.commands に宣言された
read-only な用途に限る。
gh — gh issue view <ref> --json number,title,body,labels,state のみ。git — git status、git diff、git log、git rev-parse、git show のみ。
対象 project の test command（npm test、pytest など）は 入力として与えられたもの
だけを実行する。与えられていない command を推測して実行しない。実行前に、その command を
利用者へ提示して確認を取り、確認の結果を result document の confirmations に記録する。
次のいずれかに当たる command は、確認を取る前に cleanup plan を提示する（§4 Step 3）:
- destructive（data 削除、schema 変更、branch や tag の削除、force push）
- external write（外部 API への書き込み、mail や message の送信、deploy）
- 対象 repository の外への書き込み
確認が得られなかった command は実行せず、対応する criterion を not_run にする。
not_run を pass に丸めない。
4. 手順
Step 0 — 前提の確認
issue_ref と target_ref が揃っているかを確認する。欠けていれば §5 に従って停止する。target_ref を解決し、commit SHA と branch 名を記録する（git rev-parse HEAD、
git rev-parse --abbrev-ref HEAD）。この 2 つは result document の target に入る。- 作業 tree に未 commit の変更があるかを
git status --porcelain で確認し、
target.dirty に記録する。dirty な tree での検証結果は再現できないので、
dirty のまま進める場合は summary にその旨を明示する。
Step 1 — 受入条件の抽出
- Issue 本文を取得し、受入条件（checkbox、「受入条件」節、
Acceptance Criteria）を
列挙する。
- 各条件に安定した
id を振る（AC-01 から連番。抽出順で固定し、実行結果で並べ替えない）。
- 条件が 0 件のときは、
status: failure / verdict: no_go を出力し、
blocking_reasons に「受入条件が定義されていない」と記録して停止する。
条件のない Issue を「問題なし」と報告してはならない。
Step 2 — 分類と risk tier
各条件について次を決める。詳細は references/test-plan.md に従う。
classification: automated（command で判定できる） /
manual（人間の観察が必要） / not_verifiable（この環境では判定できない）risk_tier: safe / confirm_required / blocked- 検証に使う
check（command、test、diff、manual observation のいずれか）
分類の根拠を 1 行で notes に残す。分類が曖昧なものを automated に寄せない。
Step 3 — test plan の提示と確認
- 分類結果を test plan として利用者に提示する。plan には、実行する command、
対象、期待結果、risk tier、想定所要時間を含める。
confirm_required の項目には cleanup plan を必ず添える。何を作り、何を戻し、
戻せなかったときに何が残るかを書く。cleanup plan を書けない操作は実行しない。- 利用者の応答を
confirmations に記録する（granted: true / false、理由、
cleanup plan）。確認なしに confirm_required の項目を実行しない。
- 対話できない実行形態（非対話 batch）では、
confirm_required の項目をすべて
not_run にして先へ進む。「対話できないから承認されたとみなす」ことはしない。
Step 4 — 実行と evidence 収集
確認済みの check を、plan の順に実行する。1 件ごとに evidence を作る。
evidence の必須項目と redaction 規則は
references/evidence.md に従う。
- command evidence: command 文字列、exit code、stdout/stderr の要約、実行時刻
- test evidence: test 名、pass/fail 件数、失敗した test の識別子
- diff evidence: commit SHA、変更 file の一覧（内容ではなく path と行数）
- manual observation evidence: 観察者、手順、観察した事実、判定
flaky の扱い: 同一 command を再実行して結果が変わった場合、成功した回を採用しない。
outcome: flaky とし、試行回数と各回の結果を evidence に残す。
中断した場合も、そこまでの evidence を保存し、未実行の check を not_run として
result document を出力する（§5）。
Step 5 — 判定
各 criterion の outcome を次のいずれかにする。
pass / fail / flaky / blocked / not_run / manual_pending / not_verifiable
outcome から status と verdict への写像は
references/verdict-rubric.md の決定表にそのまま従う。
決定表にない組み合わせを自分で判断しない。要約すると:
status: success = 全 criterion が pass か fail に確定 /
partial = 未確定の criterion が残った / failure = 検証を実施できなかったverdict: go = status: success かつ全 pass /
no_go = 1 件以上 fail、または status: failure /
conditional_go = fail が 0 件で、未確定項目のすべてに次 action と担当が書かれている場合のみ
conditional_go は「たぶん大丈夫」ではない。未確定項目が列挙され、それぞれに
次 action があることが条件である。書けないなら no_go である。
Step 6 — result document の出力
result_path に、schemas/acceptance-result.v1.json に適合する JSON を書く。
result_schema_version は 1 である。この Step は途中で失敗した場合も必ず実行する。
Step 7 — human-readable summary
result document と同じ内容を、次の順で提示する。
利用者が離席から戻ったときに、これだけで状態を復元できることが要件である。
- 判定（
verdict）と 1 行の理由
- 検証対象（Issue、repository、branch、commit、dirty かどうか）
- 受入条件ごとの outcome 一覧（id、要約、outcome、根拠 evidence の id）
- 実行した check と実行しなかった check（未実行はその理由つきで別に並べる）
- 未確定項目と次 action（担当つき）
- evidence の保存先
summary の雛形は references/verdict-rubric.md にある。
5. 失敗時の動作
| 状況 | 動作 |
|---|
| 入力が欠けている | 推測で補わない。status: failure、verdict: no_go、blocking_reasons に不足入力を記録 |
| Issue を取得できない | 再試行は 1 回まで。失敗したら status: failure |
| 受入条件が 0 件 | status: failure（Step 1-3） |
| 確認が得られない | 当該 check を not_run、status: partial |
| command が異常終了 | それ自体は failure ではない。exit code を evidence に残し、criterion を fail か blocked に分類する（環境要因なら blocked） |
| 環境が要件を満たさない | blocked。fail に丸めない |
| 途中で中断された | そこまでの evidence を保存し、未実行を not_run として status: partial を出力 |
| result document を書けない | summary を必ず標準出力へ出し、書けなかったことを明示する |
いかなる失敗経路でも、result document と summary を出さずに終了しない。
6. 完了条件（completion check）
以下がすべて真になったときにだけ、この Skill は完了したと報告してよい。
1 つでも偽なら status は success にならない。
- 受入条件をすべて列挙し、それぞれに
id と classification と outcome がある。
pass の criterion に、それを裏づける evidence が 1 件以上結び付いている。- 実行した check と実行しなかった check が、summary で分けて示されている。
confirm_required の check はすべて、確認記録（confirmations）を伴っている。- evidence に token、secret、環境変数の値、無関係な file の内容が含まれていない。
- result document が
schemas/acceptance-result.v1.json に適合している。
status と verdict が決定表と矛盾していない。- 未確定項目のすべてに次 action と担当がある（
conditional_go の必要条件）。
7. Agent 差異
対応 Agent の差、fallback、再読み込みの方法は
references/agent-compatibility.md を参照する。
version ごとの変更点・期待効果・制約は
references/changelog.md にある。
8. 参照
