PR・merge・archive

完了の境界を3段階で捉える

pr-create成功後の状態はawaiting-archiveです。PRを人間が確認してmergeを判断し、archive後にarchivedとなって初めてjobが閉じます。

実装・build-fixer・code-fixerの最終変更が直近のverificationより新しい場合、PR作成へ進む前にverificationへ戻ります。Standardはその後にADRを判断し、FastはADRを省いて直接PRを作成します。

状態名。 現行のJobStatusにawaiting-mergeやcompletedはありません。運用表示でもawaiting-archiveを使用します。

ADRはrequestで候補化し、agentが必要性を判断する

adrはrequest.mdのMetaに必須です。ただしtrueは「必ずADRを書く」ではなく、「ADRに値するかを判断する」指定です。

- **adr**: true

ADRの有無は実装完了の合否ではありません。長期的に残すべき設計判断があるか、という別の軸です。

PR作成は決定的なCLI step

pr-createはagentへGitHub操作を任せず、GitHub REST APIを使います。titleとbodyもrequest.mdとjob stateから組み立て、commit messageには依存しません。

run --jsonではawaiting-archiveをresult: "pr-created"として返し、prUrlを機械的に取得できます。

人間がmerge前に確認する

SpecRunnerのgate通過は、merge判断の代替ではありません。PR上でrequest・実装差分・検証根拠を照合します。

PR commentのattestationとrepository内の証跡の対応は監査と証跡で確認できます。

承認の境界。 確認後にjob archive --with-mergeを実行する行為が、人間によるmerge承認です。Issue起点の無人mergeは推奨しません。

archiveを記録してからmergeする

推奨経路は--with-mergeです。archiveのfolder移動とstateをfeature branchへ先にcommitし、そのcommitがPR headへ反映された後でchecksとmerge可否を評価します。

# archive前にidentityとslugの一意性を固定
npx specrunner job ls --all --json
npx specrunner job show <job-id>
npx specrunner job archive --with-merge my-feature
# cleanup後はslugで表示し、出力されたJob IDを固定値と照合
npx specrunner job show my-feature

一覧で同じslugの非終端jobが意図した1件だけで、そのJob IDが固定値と一致する場合だけarchiveします。

高リスクpathは自動mergeを止める

{
  "version": 1,
  "archive": {
    "protectedPaths": [
      ".github/workflows/**",
      "infra/production/**"
    ],
    "postMergeVerify": [
      "npm ci",
      "npm test"
    ]
  }
}

protectedPathsに一致するとarchive commitを記録した時点で停止します。PRを人間が確認して手動でsquash mergeし、同じ--with-mergeを再実行するとpost-merge cleanupへ進めます。file listがAPI上限でtruncateされた場合もfail-closedで停止します。

postMergeVerifyはmerge SHAの一時worktreeで順番に実行します。command失敗は「merge済み」のescalationとなり、自動rollbackしません。base branchを修正してからarchiveを再実行します。fetchやworktree作成自体に失敗した場合はwarningで続行するため、「未検証」の表示を見落とさないでください。

既定timeoutと全設定キーはConfigurationを参照してください。

停止条件と次の操作

同じcommandを再実行して収束させる

PR作成とarchiveは再実行を前提にしています。停止時にstate、worktree、feature branchを先に削除せず、原因を解消して同じslugを使います。

# archive前にidentityとslugの一意性を固定
npx specrunner job ls --all --json
npx specrunner job show <job-id>
npx specrunner job archive --with-merge my-feature
# cleanup後はslugで表示し、出力されたJob IDを固定値と照合
npx specrunner job show my-feature

同じslugの非終端jobが意図した1件だけで、一覧のJob IDが固定値と一致することを再実行前にも確認します。

具体的なerror別の復旧commandはトラブル対応を参照してください。