[Engineering] Introduce Batch and Merge Skills

[mao2009]

親Issue

#6

目的

PSXRecompStudioで運用しているBatch Skill / Merge Skillの開発ワークフローをPureSharpにも導入し、複数Issueの計画的な処理、Git/CI状態の検証、PR統合を再現可能な手順として標準化する。

PureSharp v1.0.0までのIssue数が増えるため、個々の実装だけでなく「安全に継続開発できる開発基盤」を整備する。

背景

PureSharp v1.0.0 Roadmapでは、Diagnostic contract、Analyzer品質、Purity、Immutability、FluentIf、NuGet、Compatibility、Documentation、Releaseと複数のIssueを段階的に処理する。

PSXRecompStudioで実績のあるBatch / Merge workflowをPureSharpへ適用することで、Issue選定から実装、検証、PR、mergeまでの手順を統一する。

Batch Skill

必須機能

• Issue一覧から実行可能なIssueを選定する
• Issue間の依存関係を確認する
• 独立Issueを並列実行候補として分類する
• 実行順序を決定する
• 各Issueの実装結果を収集する
• 失敗Issueと未実行Issueを明確に区別する
• 人間によるapprovalが必要なポイントを明示する

安全性

• 同一ファイル・同一領域を変更する可能性が高いIssueを無条件に並列実行しない
• dependency未解決のIssueを実行しない
• working treeやbranch状態を確認してから実行する
• 実行結果を推定せず、実際のGit/CI状態を記録する

Merge Skill

必須機能

• branch名を確認する
• base branch / base commitを確認する
• working tree状態を確認する
• result commitを確認する
• test / build / CI結果を確認する
• PR存在・状態を確認する
• merge可能条件を判定する
• merge後のtarget branch状態を確認する

Merge Gate

以下を確認できない場合、merge済みと判断してはならない。

• branch
• base commit
• result commit
• PR
• CI / tests
• working tree

最終報告

PureSharpでも以下の2層構造を標準とする。

Human Report

• 何を変更したか
• なぜ変更したか
• テスト結果
• PR / merge結果

AI Report

• Evidence: confirmed / inferred / unverified
• Git State
  • branch
  • base commit
  • result commit
  • PR
  • working tree
• Verification
  • build
  • tests
  • CI
  • package / consumer verification

AI Reportでは、未確認事項を成功したものとして扱わない。

導入方針

• PSXRecompStudioのBatch Skill仕様をPureSharp向けに整理する
• PSXRecompStudioのMerge Skill仕様をPureSharp向けに整理する
• PureSharp repository内で利用できるSkill定義を追加する
• Batch workflowでPureSharpの複数Issueを実際に処理する
• Merge workflowでPRの検証・統合を実際に行う
• Git状態の最終報告フォーマットを標準化する
• CI結果をmerge gateとして扱う
• 失敗・未確認・推定を明確に区別する
• 開発者向けドキュメントにworkflowを記載する

完了条件

• Batch SkillをPureSharp開発で利用可能
• Merge SkillをPureSharp開発で利用可能
• Issue選択 → 実装 → PR → verification → merge の一連のworkflowを検証済み
• Git状態を機械的に確認できる
• CI / test結果をmerge判断に利用できる
• Human Report / AI Reportの2層最終報告を採用
• confirmed / inferred / unverifiedの証拠区分を採用
• workflow自体の利用方法が文書化されている

非スコープ

• PureSharp Analyzerの機能追加
• Batch / Merge SkillをPureSharp本体のNuGet APIとして提供すること
• PSXRecompStudio固有の機能をそのまま移植すること
• AIエージェントの実装そのものをPureSharpで行うこと

成果物

• PureSharp向けBatch Skill仕様
• PureSharp向けMerge Skill仕様
• Skill利用手順
• 最終報告フォーマット
• 実運用によるworkflow検証結果

[mao2009]

PR #19 merged — Merge Skill dogfood 完了報告

PR #19 を merge しました。この Issue はまだ close しません。

Merge 実績

項目	値
PR	#19
Approved / merged HEAD	23d254c4432885179b7a7ee9678541bc45a5907e
Merge commit	e099d62af5add11193528018c693a0055e871fae
Merge method	Merge commit（expected HEAD 拘束あり）
main HEAD	e099d62
Post-merge CI (main)	completed / success

Merge Skill dogfood 結果（CONFIRMED）

Merge Skill を SSOT として、以下の一連の workflow を実運用で通しました。

verification → MERGE CANDIDATE → human review
→ explicit human approval → merge execution → post-merge verification

• 技術 gate A–F をすべて CONFIRMED で通過
• CI evidence を exact HEAD に拘束（stale CI を排除）
• merge 直前の atomic re-check を実施（HEAD / CI / blocking review / mergeability / repository policy / merge method）
• expected HEAD を指定して merge（PR が動いていれば host 側が拒否する方式）
• post-merge verification 完了（PR MERGED / merge commit の親に承認 SHA / main への統合 / main CI success）

本 PR 期間中に判明し修正した contract 欠陥

実際に merge を試みるまで表面化しなかった構造的欠陥を 2 件修正しています。

1. self-authored PR で human approval gate が永久に満たせない — GitHub は PR author 自身の APPROVE を許可しないため、requiredApprovals を「GitHub APPROVED review record 数」と固定すると単独メンテナでは gate を満たせませんでした。approval source を 2 系統（第三者 GitHub review / exact-HEAD 拘束の out-of-band approval）に分離し、repository policy 優先・self-approval 捏造禁止を明文化しました。
2. mergeMethod: "ff-only" が実行不能 — GitHub PR merge は merge / squash / rebase のみ提供します。schema から ff-only を削除しました。

今回の merge は Source 2（out-of-band approval）で実行しました。GitHub 上の第三者 approval は 0 件のままであり、self-approval として計上していません。

残存する完了条件

• Batch workflow で複数 Issue を実際に処理する（対象予定 [Analyzer] Establish diagnostic contract and rule catalog SSOT #7–[Analyzer] Define pure method contract and interprocedural analysis #10）
• Batch Skill の実運用検証
• 成果物「実運用による workflow 検証結果」

Merge Skill 側の実運用検証は完了しましたが、Batch Skill 側が未検証のため本 Issue は OPEN のまま維持します。

[mao2009]

Batch/Merge Skill 実運用結果 — PR #20 → PR #21 連続マージ

Issue #7 (PR #20) と Issue #8 (PR #21) の実運用で確認された workflow findings を記録する。

Finding 1: Stacked PR の CI blind spot

事象

.github/workflows/upload_nuget.yml のトリガは以下:

on:
  pull_request:
    branches: [ main ]

base が main でない PR では workflow が発火しない。実際に PR #21 は base が
feature/issue-7-diagnostic-ssot であった間、build-test の run が 1 件も存在しなかった
(gh run list --branch feature/issue-8-regression-coverage → [])。

CodeRabbit も同じ条件で skip される:

Auto reviews are disabled on base/target branches other than the default branch.

影響

• stacked PR は base を main に retarget するまで build/test evidence も review evidence も取得できない
• Merge Skill の gate C (Build/Test)・D (CI)・E (Reviews) は stacked 状態では原理的に CONFIRMED にできない
• stack の各段は「前段が main にマージされ、自身が main に retarget された後」に初めて検証可能になる
• したがって stacked batch では マージのたびに後続 PR の evidence を全て再取得する必要がある

補足: retarget だけでは CI は発火しない

base 変更は pull_request の edited イベントであり、デフォルトのトリガ種別
(opened / synchronize / reopened) に含まれない。PR #21 では base を main に
変更しただけでは run が作られず、close → reopen (reopened) で初めて発火した。
push (synchronize) も base が main でない時点で行うと条件に合致しない。

Batch Skill への含意

Batch Skill の batch gate は各 issue について「CI passed for the PR HEAD (CONFIRMED)」を
要求するが、stacked 構成ではこれを満たせない期間が構造的に存在する。
stacked PR を batch に含める場合、この gate は「retarget 後に評価する」ものとして
実行グラフ上で順序制約を持つ。

Finding 2: merge.config.json の $description と Merge Skill schema の不整合

事象

.kiro/merge.config.json は $description キーを持つが、Merge Skill の Configuration
schema は requiredApprovals / mergeMethod / deleteBranchAfterMerge の 3 キーのみを
定義し、次のように規定している:

Missing file, malformed JSON, an unknown key, a key of the wrong type, or
requiredApprovals < 1 → CONFIG ERROR → MERGE BLOCKED.

文字どおり読むと $description は unknown key に該当し、本リポジトリの全マージが
恒久的に BLOCKED となる。一方 $description の内容自体は
「SKILL.md が SSOT である」という設計意図を説明するものであり、削除すると
config 単体を読んだ際の誤用リスクが上がる。

評価

PR #21 のマージ blocker とはしなかった。schema と実ファイルの不整合であり、
PR #21 の変更内容 (test-only) とは独立しているため。

follow-up 候補

• 案 A: Merge Skill schema に「$ 始まりのキーは注釈として無視する」規則を明記する
• 案 B: $description を削除し、説明を SKILL.md 側に一本化する

案 A を推す。config 単体でも SSOT の所在が分かる利点を保ちつつ、
schema と実装を一致させられる。

検証済みの動作 (positive findings)

• Merge Skill の HEAD binding は機能した。PR test: strengthen existing rule regression coverage (#8) #21 は restack により HEAD が
  cd67257 → 052fb57 に変化し、旧 evidence (CI・CodeRabbit) は全て無効として
  再取得を要求できた
• self-authored PR に対する out-of-band approval が、GitHub の
  「作者は自分の PR を approve できない」制約下で gate を成立させた。
  GitHub APPROVED review としては計上しておらず (reviews: [] のまま)、
  evidence の捏造は発生していない
• force push を伴わない restack (main を feature ブランチに merge) により、
  後続の PR docs: harden RT semantics and purity boundaries (#9) #22 の merge-base が保全され、docs: harden RT semantics and purity boundaries (#9) #22 の diff が汚染されなかった。
  rebase を選んでいた場合 docs: harden RT semantics and purity boundaries (#9) #22 の diff に Issue [Analyzer] Strengthen existing rule regression coverage #8 の変更が混入していた