durable workflow dogfood runbook

この runbook は、Issue 作成、実装、review / validation、PR publication、agent-team 実行で durable workflow を日常運用に使い続けるための手順である。 自然言語 summary や作業ディレクトリの存在ではなく、review-orchestrator の stdout JSON、durable workflow state、effect outcome、validation evidence を source of truth にする。

Loop Engineering の Skill 入口と profile 境界は loop-engineering reference を参照する。 この runbook は controller が参照する既存 durable workflow contract であり、loop-state.v1 や profile policy を所有しない。

common rule

  • workflow ID、cycle ID、current phase、baseline head、current head、required action を確認してから再開する。
  • repo tmp/ や worktree path は resource として扱い、workflow identity にしない。
  • crash、新しい shell、別 Agent への handoff 後は、stable workflow state と artifact reference を inspect してから続行する。
  • unknown、waiting_input、blocked、stale evidence、head mismatch は success に丸めない。
  • external effect の intent が残り outcome が unknown の場合は、GitHub や filesystem の final read で reconciliation してから retry を判断する。
  • human input が必要な state は needs_user_decision / waiting_input として残し、通常 validation 成功で代替しない。

進行中の Issue 作成 family を横断して見る時は、review-orchestrator issue workflow-family-list を使う。 単一 family の completion 判定は従来どおり workflow-family-status を使い、横断一覧は blocked 件数、phase、next_required_action を読むための read-only view として扱う。

new issue creation

新規 Issue 起票は durable Issue creation / research family を使う。 task-research、github-issue-validation、github-issue-breakdown の research packet、validation result、Issue create outcome、post-create result、sub-issue link、parent finalization を durable state 上の evidence として確認する。

Partial Issue creation や create outcome unknown が残る場合は duplicate Issue を作らない。 review-orchestrator issue workflow-family-status、Issue URL の final read、post-create artifact の順に確認し、resume または manual confirmation に進む。

implementation

既存 Issue は fix-github-issue、Issue なし local plan は implement-from-plan の durable implementation family を使う。 着手前に claim / readiness / capability preflight を通し、実装後は implementation status で phase、obligations、evidence、effect outcomes を確認する。

Process crash や new shell 後は、worktree の branch 名だけで再開判断をしない。 workflow ID、current phase、baseline head、current head、changed files、validation commands、required action を durable state から読み、stale evidence や candidate file drift があれば readiness / checkpoint に戻す。

review and validation

multi-review、review-only、agent-simplify、e2e-workflow-gate の結果は durable evidence として扱う。 review attempt completed は merge-ready や PR-ready ではない。 review gate、validation gate、conflict gate、thread drain、final simplify、final E2E の obligations が残っていないことを evidence manifest と report で確認する。

Stale evidence、head mismatch、final E2E mismatch、parse failure、timeout、artifact missing、transport failure は success にしない。 e2e=final|both では phase run の e2e_success または user-confirmed skip evidence を final gate として確認し、通常 test success だけで E2E を満たしたことにしない。

PR publication

create-pr と update-pr は durable publication flow を使う。 push、PR create、PR edit は external effect として intent / outcome / idempotency を残し、unknown outcome を duplicate mutation で解消しない。

PR publication 後は GitHub final read で base branch、head branch、head SHA、draft state、assignee、body digest を確認する。 PR 本文は reviewer-facing にし、internal workflow option や gate 名をそのまま露出しない。

agent-team

agent-team-run は親 Issue queue / worker / integration state を source of truth にする。 unknown worker や blocked worker を completion として扱わず、即 duplicate dispatch しない。 queue state、request / response、worker result、cleanup evidence、child workflow state、GitHub evidence を照合してから次の dispatch、integration、manual recovery を判断する。

Agent-team は明示された親 Issue queue の運用であり、通常の Issue 作成や github-issue-breakdown 後に自動展開しない。 Loop Engineering #862 の daily triage / work discovery はこの runbook の対象外で、必要なら #862 側の follow-up に分ける。

incident feedback

新しい failure は、修正だけで終えず次のどれに還元するかを記録する。

  • workflow contract 不足
  • acceptance matrix row 不足
  • serialized fixture 不足
  • effect / recovery bug
  • docs / skill routing drift
  • live acceptance gap

Deterministic に再現できるものは最小 event / state fixture へ落とす。 外部サービスや実 Agent が必要なものは opt-in live acceptance として、auth failure、rate limit、billing、service failure、cleanup requirement を分類する。 GitHub mutation を伴う live acceptance は review-orchestrator issue durable-acceptance-live で対象 repo、actor、cleanup policy を明示し、--yes と --cleanup on が揃うまで実行しない。通常 CI では --fake-github の deterministic path だけを使い、cleanup plan/result と artifact path を検証する。 runbook と実運用がずれた場合は、skill 本体だけでなく docs/skills/*、workflow contract、acceptance matrix、関連 guide を同期して更新する。

このページは生成物です。原本は元リポジトリ側にあります。