i-dev-final-check

description	dev workflow 向けの最終チェック。PR 前に品質ゲート、docs 整合、設計書昇格、Issue 更新をまとめて確認する。
name	i-dev-final-check

I Dev Final Check

dev workflow の PR 前最終ゲート。 前段で作られた証跡を集約し、必要なら docs 更新や設計書昇格を行ったうえで、PR に進めるか判定する。

いつ使うか

タイミング	このスキルを使用
/issue-review-code または /issue-verify-code で Approve 後	✅ 必須
dev workflow の PR 作成前	✅ 必須

ワークフロー内の位置: implement → review-code → i-dev-final-check → i-pr → close

入力

ハーネス経由（コンテキスト変数）

常に注入される変数:

変数	型	説明
issue_id	str	正規化済み Issue ID（GitHub 数値または local ID）
issue_ref	str	人間可読の Issue 参照（GitHub では #<issue_id>、local では bare ID）
step_id	str	現在のステップ ID

手動実行（スラッシュコマンド）

$ARGUMENTS = <issue_id>

解決ルール

コンテキスト変数 issue_id が存在すればそちらを使用。 なければ $ARGUMENTS の第1引数を issue_id として使用。

issue_ref はハーネス経由ではプロンプトに自動注入される（prompt.py 側で provider 別に整形）。手動実行時は issue_id から導出する: GitHub 数値 ID なら #<issue_id>、local-* 形式なら bare ID（# を付けない）。

前提知識の読み込み

1. docs/dev/kaji-workflow.md
2. docs/dev/workflow_completion_criteria.md
3. docs/dev/documentation_update_criteria.md
4. docs/dev/shared_skill_rules.md
5. docs/README.md
6. _shared/promote-design.md

共通ルール

• _shared/report-unrelated-issues.md — 作業中に発見した無関係な問題の報告ルール

実施内容

1. worktree と branch を解決する
2. 前段の証跡を集約し、事後確認を除く Issue 完了条件との照合を行う
3. 設計書の「影響ドキュメント」と実差分を確認する
4. 品質ゲートを実行する（後述 Step 4 詳細）
5. docs 更新の最終確認を行い、必要なら修正する
6. 設計書昇格判定 → 必要なら昇格、または既存 docs 更新の有無を確認する
7. Issue 本文の完了条件を照合し、### ワークフロー完了後の確認項目 を除く充足状態を更新する 7.5. 設計書を Issue 本文の NOTE ブロック直下に添付する
8. Issue に最終チェック結果をコメントする

Step 2 詳細: 前段証跡の集約と完了条件照合

2-1. 前段コメントの走査

uv run kaji issue view [issue_id] --comments

以下の完了報告コメントが存在するか確認する:

ステップ	期待するコメント	必須の内容
issue-design	「設計書作成完了」	設計書パス、テスト戦略、影響ドキュメント
issue-review-design	「設計レビュー結果」	Approve / Changes Requested 判定
issue-fix-design → issue-verify-design	（経由した場合のみ）「修正確認結果」	Approve 判定
issue-implement	「実装完了報告」	pytest 出力（S/M/L 結果）、品質チェック結果
issue-review-code	「コードレビュー結果」	Approve / Changes Requested 判定、独立テスト実行結果
issue-fix-code → issue-verify-code	（経由した場合のみ）「修正確認結果」	Approve 判定

fix/verify サイクルの扱い: 実 workflow では issue-review-* が Changes Requested を返した場合、 issue-fix-* → issue-verify-* を経由して再度 Approve を得てから final-check に到達する。 コメント履歴に過去の Changes Requested が残るのは正常な状態であり、最新の判定結果（verify の Approve）を 権威ある判定として採用する。過去の Changes Requested は「解決済みの指摘」として無視してよい。

2-2. 完了条件との照合

Issue 本文の ## 完了条件 セクション（チェックボックス形式）を取得し、 末尾サブセクション ### ワークフロー完了後の確認項目 を判定対象から除外する。 残った各条件について:

1. どの前段で確認されたか を特定する
2. 確認の根拠 を前段コメントから抽出する（最新のコメントを優先）
3. 未確認の条件 があれば、この final-check で確認するか、前段への差し戻しが必要かを判断する

2-3. 前段証跡が不足している場合

差し戻しが必要な場合は root-cause に応じて以下を使い分ける。実際にどの status を返せるかは workflow YAML の final-check.on で決まり、prompt 経由で valid status 一覧が注入される （詳細は § Verdict 出力 § workflow YAML 互換ルール）。

root-cause	例	推奨 status（新 YAML）	互換 status（旧 YAML）
設計起因	設計書の影響ドキュメント評価漏れ / テスト戦略未定義 / 要件解釈の食い違い	BACK_DESIGN	BACK（YAML が BACK のみ valid な場合）
実装起因	前段コメント欠落 / 最新判定が Changes Requested のまま / 品質ゲート未通過 / docs 更新漏れ	BACK_IMPLEMENT	BACK（YAML が BACK のみ valid な場合）
完了条件未充足	最新の判定結果は Approve だが Issue 完了条件が未充足	この final-check で対応可能なら RETRY、不可能なら root-cause に応じ BACK_DESIGN / BACK_IMPLEMENT / BACK	同左

root-cause 不明の場合: 自動で BACK_DESIGN 等を default にせず、ABORT を返して運用に escalation する。

Step 4 詳細: 品質ゲートの実行

この starter は Python 単一スタックである。baseline artifact が clean の場合は以下の 1 本を実行する。

cd [worktree_dir] && source .venv/bin/activate && make check

make check は ruff / format / mypy / pytest を一括で実行する（AGENTS.md の pre-commit 契約と同一）。

artifact が known_failures の場合だけ、同じ対象を次の 2 コマンドへ分離する。

cd [worktree_dir] && source .venv/bin/activate && make lint format typecheck
cd [worktree_dir] && source .venv/bin/activate && python -m kaji_harness.scripts.baseline_precheck --compare

特定マーカーや変更タイプ固有の検証が必要な場合は、設計書「テスト戦略」に従い追加実行する:

変更タイプ	追加検証
docs-only	make verify-docs
metadata-only / packaging-only	uv lock --check または設計書で定めた変更固有検証
通常	追加なし（make check で十分）

baseline failure の扱い: [worktree]/.kaji-artifacts/baseline/baseline.json が known_failures の場合、上記の分離 gate を使う。 verdict: ok、regression 0 件だけを許可する。詳細は docs/dev/baseline-check.md を正本とする。

Step 6 詳細: 設計書昇格判定

_shared/promote-design.md の手順に従い、 draft/design/issue-[issue_id]-*.md を恒久ドキュメントへ昇格するか、既存 docs に統合するかを判定する。

判定軸:

• 新規機能・新規 ADR 相当の決定 → 恒久 docs（docs/adr/ ほか）へ昇格
• 既存 docs の更新で吸収可能 → 既存 docs を更新（昇格しない）
• 設計の決定が draft 段階のまま留めるべき軽微な変更 → 昇格不要

Step 7 詳細: Issue 本文の完了条件更新

PASS の場合

Issue 本文の workflow 内完了条件のチェックボックスを [x] に更新する。 ### ワークフロー完了後の確認項目 内のチェックボックスは更新せず、[ ] のまま維持する。

# 本文を取得
uv run kaji issue view [issue_id] --json body -q '.body' > /tmp/issue-body.md

# チェックボックスを更新（事後確認より前にある確認済み条件だけを [x] に変更）
# 例: sed -i 's/- \[ \] 条件A/- [x] 条件A/' /tmp/issue-body.md

# 更新を反映
uv run kaji issue edit [issue_id] --commit --body-file /tmp/issue-body.md

BACK の場合

チェックボックスは [ ] のまま残す。コメントで未充足条件と戻し先を明示する。

RETRY の場合

本文更新は行わない（軽微修正後に再実行するため）。

Step 7.5 詳細: 設計書の Issue 本文添付

Step 7（完了条件更新）の後、Step 8（最終チェックコメント）の前に、設計書を Issue 本文の NOTE ブロック直下に添付する。

7.5-1. 冪等性チェック

uv run kaji issue view [issue_id] --json body -q '.body' | grep -q '^## 設計書'

既に ## 設計書 セクションが存在する場合はスキップする（位置の移動はしない）。

7.5-2. 添付対象の決定

条件	添付対象
Step 6 で恒久 docs へ昇格を実施した	昇格後の確定版（docs/... 配下）
昇格対象外	draft/design/ 版

7.5-3. 添付位置の判定（NOTE 直下挿入ルール）

Issue 本文を行単位で走査し、以下のルールで挿入位置を決定する:

ケース	挿入位置
NOTE ブロックが1つ存在する（標準）	NOTE ブロック終端の次の空行の後
NOTE ブロックが複数存在する	最初の NOTE ブロック終端の次の空行の後
NOTE ブロックが存在しない（古い Issue）	本文先頭
既に ## 設計書 が別位置に存在する	スキップ（7.5-1 で検出済み）

NOTE ブロックの終端判定: > [!NOTE] から始まり、> プレフィックスの連続行が途切れた最初の空行。

7.5-4. 添付フォーマット

昇格済みの場合:

## 設計書

恒久ドキュメントとして昇格済み: [`docs/...`](https://github.com/apokamo/kaji/tree/main/docs/...)

未昇格の場合:

## 設計書

<details>
<summary>クリックして展開</summary>

(設計書全文)

</details>

7.5-5. Issue 本文への挿入

# 本文を取得
BODY=$(uv run kaji issue view [issue_id] --json body -q '.body')

# NOTE ブロック終端位置を検出し、その次の空行の後に挿入
# new_body = body[:insert_at] + 設計書セクション + body[insert_at:]
uv run kaji issue edit [issue_id] --commit --body-file /tmp/issue-body-updated.md

7.5-6. フォールバック

本文サイズ上限超過等で uv run kaji issue edit に失敗した場合:

1. Issue コメントに設計書全文を投稿する
2. 本文には ## 設計書 セクションとコメントへのリンクのみを追記する
3. フォールバック発生時も PASS 扱い（設計書自体は参照可能であり、添付位置の問題に過ぎないため）

Step 8 詳細: 最終チェックコメントのテンプレート

verdict マーカーの無条件付与（必須）: 最終チェック結果コメントには 常に --verdict-step final-check --verdict-status <STATUS> を付与する。<STATUS> は本 skill が返す status（PASS / RETRY / BACK_DESIGN / BACK_IMPLEMENT / BACK。旧 YAML 互換で BACK に丸める場合は BACK）に置換する。CLI が body 1 行目に <!-- kaji-verdict: step=final-check status=<STATUS> --> を決定的に付与し、issue-design Step 1.6 の BACK 再入検出は BACK / BACK_DESIGN マーカーのみを design 再入として数える（契約の正本は CLI コード。ADR 008 決定 3）。「BACK のときだけ付ける」条件付き出力は禁止（決定 3。PASS / RETRY でも常に付ける）。--body-file - は stdin から body を読むため、フラグは以下の順で付与する。

uv run kaji issue comment [issue_id] --commit \
  --verdict-step final-check --verdict-status <STATUS> \
  --body-file - <<'EOF'
## 最終チェック結果

### 前段証跡の確認

| ステップ | コメント有無 | 最新判定 |
|----------|------------|---------|
| issue-design | ✅ | 設計書作成済み |
| issue-review-design | ✅ | Approve |
| (fix-design → verify-design) | (経由した場合) | (Approve) |
| issue-implement | ✅ | テスト全件 PASSED（または baseline 一致） |
| issue-review-code | ✅ | Approve |
| (fix-code → verify-code) | (経由した場合) | (Approve) |

### workflow 内完了条件の充足状態

| 条件 | 充足 | 確認元 |
|------|------|--------|
| (条件1) | ✅ / ❌ | (どのステップ/コメントで確認) |
| (条件2) | ✅ / ❌ | (どのステップ/コメントで確認) |

### 品質ゲート

| ゲート | 結果 | 備考 |
|--------|------|------|
| `make check` | PASS / FAIL | ruff / format / mypy / pytest 一括 |
| 変更タイプ固有検証 | PASS / FAIL / N/A | 例: `make verify-docs` / `uv lock --check` |

### docs 整合

- 設計書昇格: 実施 (`docs/...`) / 不要
- docs 更新: 実施 / 不要

### Issue 本文更新

- チェックボックス更新: 実施 / 不要
- 設計書添付: 実施 / スキップ（既存） / フォールバック（コメント投稿）

### 判定

PASS / RETRY / BACK_DESIGN / BACK_IMPLEMENT / BACK
EOF

後方互換: 旧 workflow YAML が BACK のみを valid とする場合は BACK を返す。詳細は § Verdict 出力 § workflow YAML 互換ルール。

Verdict 出力

---VERDICT---
status: PASS
reason: |
  dev workflow の最終チェックを完了し、PR に進める状態を確認した
evidence: |
  前段証跡を集約し、事後確認を除く workflow 内完了条件の充足を確認した。Issue 本文の対象チェックボックスを更新済み
suggestion: |
---END_VERDICT---

status の選択基準

status	条件
PASS	事後確認を除く workflow 内完了条件がすべて充足し、Issue 本文更新済み
RETRY	final-check 文脈で閉じる軽微修正が必要
BACK_DESIGN	設計起因の不足（影響ドキュメント評価漏れ / テスト戦略未定義 / 要件解釈の食い違い 等）。design に戻す。final-check.on に BACK_DESIGN が定義されている YAML でのみ使用
BACK_IMPLEMENT	実装起因の不足（前段コメント欠落 / 品質ゲート未通過 / docs 更新漏れ 等）。implement に戻す。final-check.on に BACK_IMPLEMENT が定義されている YAML でのみ使用
BACK	旧 YAML（BACK のみ valid）における差し戻し。後方互換のため残置。未充足条件と戻し先を suggestion に明示
ABORT	重大な前提不整合

BACK_DESIGN / BACK_IMPLEMENT / BACK / ABORT はいずれも suggestion フィールド必須。harness 側の verdict.py が空 suggestion を VerdictParseError で弾く。

workflow YAML 互換ルール

i-dev-final-check は複数 workflow から呼ばれるため、skill 側は prompt 経由で注入される valid status 一覧（prompt.py:75, 92-97 の valid_statuses = list(step.on.keys())）を 権威ある情報源として扱う。prompt が「使ってよい」と言った status のみ返すことで多 workflow 互換性が成立する。

呼び出された workflow の final-check.on キー	skill が返すべき status
BACK_DESIGN と BACK_IMPLEMENT の両方が定義（例: dev.yaml）	root-cause を判定して BACK_DESIGN / BACK_IMPLEMENT を使い分け。無印 BACK は使わない
BACK のみが定義（例: implement-to-pr.yaml）	従来通り BACK を返す（root-cause 判定結果に関わらず YAML 制約に従う）
BACK 系が一切未定義（例: dev-local.yaml）	BACK 系を返さない。RETRY（軽微修正）または ABORT（重大な前提不整合）で表現
BACK_DESIGN のみ / BACK_IMPLEMENT のみ定義	想定外構成。ABORT を返し、運用に workflow YAML の見直しを促す

prompt と skill 出力に不整合が生じた場合（valid status に無い status を返した場合）、harness の InvalidVerdictValue で弾かれる。skill 側はあくまで prompt 内 valid status のみ返す。