[roadmap] Claude Code–Codex Review Loopの実装roadmap

このIssueの役割

本repositoryの親roadmap Issueです。合意済みの完成イメージ、implementation plan、各実装子Issueをここから参照します。

進行中の議論と決定はGitHub上のIssue / PRを正式なconversation sourceとし、target behaviorに影響する決定はtarget-experience.mdのdecision logへD-NNNとして記録します。

設計baseline

文書	内容	状態
docs/plans/target-experience.md	ユーザーから見た完成状態、state model、権限境界、失敗・復旧、MVP boundary	Agreed
docs/decisions/0001-independent-v2.md	独立したv2として再設計する判断	Accepted
docs/decisions/0002-independent-reimplementation.md	参考実装の調査結果、naming decision、選択移植ポリシー	Accepted
docs/plans/implementation-plan.md	設計原則、component C-01〜C-15、Phase 0〜17、受入条件	Accepted
docs/architecture/overview.md	役割、主経路、component map、不変条件の1ページ要約	Accepted
docs/architecture/README.md	component一覧のindex	Accepted

設計の中核は次の4点です。

• ControllerはLLMを内包しない決定論的state machineとし、GitHub、worktree、agent、test、CI、state、mergeを調整する
• Claude Codeを既存の対話型sessionのままhost / coderとして使用する
• Codexはreview turnごとにfreshなdurable read-only subprocessとして起動し、隔離checkout内でのみ検証する
• GitHub Issue / PRを正式なconversation sourceとし、各logical turnを投稿・read-after-write確認してから次agentを起動する

正常な最終状態は、ユーザーの明示承認を経てGitHub上のmerge完了を確認したMERGEDです。

現在の状態

Phase 0（品質ゲートとP-001）からPhase 8（C-08 active host protocolとstep engine、#13）までの実装が完了しました。Phase 8はPR #38 / #39 / #42 / #43 / #44 / #45 / #46 / #47 / #48 / #49の10 PR構成で、advanceの3 outcome、headless復旧経路、durableな緊急停止、BLOCK_INTERVENTION搬送路、RecordIntegrityIncidentの実行まで閉じ、#13はcloseしました。Phase 8の着手前レビューでC-01の欠陥（#40）が見つかり、PR #41で修正済みです。Phase 9（C-09 Codex fresh runtimeと隔離checkout、#14）は進行中で、reviewer用の独立checkout（PR #56）とCodex canary harnessの第1段階（PR #57、専用CODEX_HOMEと固定argvの純粋builder）をmerge済みです。残りはprocess facade（sandbox強制のpreflightと起動前fail closed、実Codex起動）、手動canary、prompt / ReviewContext、AC-C09-04の三者照合です。並行して、role別provider選択の追加案D-032（#52、Proposed）の設定契約・永続化・runtime照合をPR #53 / #54 / #55で実装済みですが、native adapterは未実装で、D-032のbaseline採択はGitHub上の明示合意recordを待ちます。なおAC-C06-03の「実repository書込の失敗」はsandboxを持つC-09の担当範囲であり、#11はその統合完了まで開いたままにします。実行可能なreview loopはまだありません。

• PR #1 でrepository基盤、Apache-2.0統一、最小CI、repository contract testを整備し、merge commit 30e5023としてmainへ取り込み済みです
• PR #3 で、本Issueの番号を設計文書へ記録し、merge commit 46ad187としてmainへ取り込み済みです
• PR #4 でimplementation planと新しい文書構成を整備し、merge commit 5f8955fとしてmainへ取り込み済みです
• Phase 0〜17の実装子Issue（#5〜#22）を発行済みです
• PR #26 でPhase 1（C-01）の高水準実装計画を確定し、merge commit da532aeとしてmainへ取り込み済みです。完全遷移・guard排他・到達可能性の正本はC-01実装のcode registryとproperty / sequence testに置きます（#6 に実装checklistを記載済み）
• PR #27 でC-01 domain state machineを実装し、merge commit 7ce0e35としてmainへ取り込み済みです（registry 143 rule、受入test 127件、branch coverage 100%。生成した遷移表・遷移図はdocs/architecture/c01-state-machine.md）
• PR #28 でC-02 protocol schemaとcheckpoint envelopeを実装し、merge commit 60ebfd2としてmainへ取り込み済みです（29 kindのschema registry、versioning / migration policyはADR-0004、test 152件、branch coverage 100%）
• PR #29 でC-03 process abstractionを実装し、merge commit 32901ccとしてmainへ取り込み済みです（WindowsはJob Object新規実装・POSIXはprocess group、停止機構はADR-0005、test 55件、両OSでbranch coverage 100%）
• PR #30 でC-04 security policyを実装し、merge commit 66615b4としてmainへ取り込み済みです（redaction 13 pattern・trust rule・permission profileの純粋policy、評価意味論はADR-0006、禁止flag contract test導入でP-006ゲートが完備、test 122件）
• PR #31 でC-05 GitHub transportを実装し、merge commit 53c004fとしてmainへ取り込み済みです（未検証metadataのI/O・search-firstの冪等投稿・予約marker CC_REVIEW_METAの正式化・thread操作、規約はADR-0007、fake ghによるtest 139件）
• PR #32 でC-06前半のrecord検証coreを実装し、merge commit 8bee105としてmainへ取り込み済みです（actor解決・D-031 allowlist受理・record chain検証（7条件）・high-water mark、chain specはADR-0008。identity/を新設）
• PR #33 でC-06後半のcredential隔離とauthority分離を実装し、merge commit 103e495としてmainへ取り込み済みです（reviewer home・OS別file権限・auto mode検出・tool permission resume gate、方針はADR-0009）
• PR #34 でPhase 7 PR-1（recordのcanonical projection）を実装し、merge commit 2faecc7としてmainへ取り込み済みです（markerへ載せるscalar射影とidempotency keyの導出規約、正本はADR-0010。ADR-0007 / 0008へ追補）
• PR #35 でPhase 7 PR-2（checkpoint storeとPR lock）を実装し、merge commit 176986cとしてmainへ取り込み済みです（atomic replace・構造化した読込結果・state root配下のPR lock、正本はADR-0011。state/を新設）
• PR #36 でPhase 7 PR-3（resume観測と承認失効）を実装し、merge commit ef43b93としてmainへ取り込み済みです（run候補の列挙と決定論的選択・advertised headの観測と承認失効・artifact bindの照合、正本はADR-0012。C-05へPR metadataのread primitiveを1つ追加）
• PR #37 でPhase 7 PR-4（resume contextとpending recordの再発行）を実装し、merge commit a143377としてmainへ取り込み済みです（resume contextの組み立て・中断recordの再発行directive・GitHub直接回答の候補列挙・crash matrix 4位置、正本はADR-0013）。これでPhase 7（AC-C07-01 / 02 / 03 / 05 / 06）が完了し、#12はcloseしました
• PR #38 でPhase 8 PR-1（action registryとprotocol schema）を実装し、merge commit 9e8d711としてmainへ取り込み済みです（C-01のHostActionを正本にしたaction registry、HOST_ACTION / SUBMITのv2確定、checkpointのhost_action section。正本はADR-0014。workflow/を新設）
• PR #39 でPhase 8 PR-2（step engine）を実装し、merge commit 5de4467としてmainへ取り込み済みです（advance / submit、typed port、result file検証、record transactionの発行、retry attemptとreceipt ledger、CHECKPOINT v2とmigration。正本はADR-0015）
• PR #42 でPhase 8 PR-2b（汎用PersistRecord executor）を実装し、merge commit fbc5a22としてmainへ取り込み済みです（投稿 -> read-after-write -> C-06検証 -> *Verified eventの組み立て -> transaction消費、chain violationのrouting、crash matrix 6窓、MachineStateのround-trip検証とintegrity stateの保存。正本はADR-0017）
• PR #44 でPhase 8 PR-3a（procedure / blockのcheckpoint表現とHaltRunの実行）を実装し、merge commit 60541eaとしてmainへ取り込み済みです（procedure 4種・block 3種のround-trip、継続のID保存、process tree台帳、停止してから保存する順序、USER_CANCEL -> CANCELLEDの完走。正本はADR-0019）
• PR #43 でPhase 8 PR-2c（AWAIT_USER搬送路と2経路の重複防止key）を実装し、merge commit 148427eとしてmainへ取り込み済みです（USER_REQUEST / USER_SUBMIT / PERMISSION_RESUME schema、awaitingごとのresult kind registry、action_id / request_idの排他によるsubmit envelope判別、run / awaiting instance / head / 正規化intentからなる重複防止key、tool permission resumeの接続、input_route語彙の確定。正本はADR-0018）
• PR #41 でC-01の欠陥（#40）を修正し、merge commit 330db76としてmainへ取り込み済みです（integrity halt gateの停止attempt identityをviolation集合から分離。追加検出で代表bindingが入れ替わると、発行したHaltRunの完了報告が拒否されていた。正本はADR-0016。Phase 8 PR-3がHaltRunを実装する前提）
• PR #45 でPhase 8 PR-3b1（runtimeとprocess entry point）を実装し、merge commit 1676f32としてmainへ取り込み済みです（正本はADR-0020。runtime/を新設）
• PR #46 でPhase 8 PR-3b2（緊急停止のdurableな表現とsignal handler）を実装し、merge commit aa2b6f6としてmainへ取り込み済みです（正本はADR-0021）
• PR #47 でPhase 8 PR-3b3（headless adapterとactive / headlessの同値性）を実装し、merge commit 677ce3aとしてmainへ取り込み済みです（正本はADR-0022）
• PR #48 でPhase 8 PR-3c（BLOCK_INTERVENTIONの搬送路と待機識別子の直和）を実装し、merge commit d567df6としてmainへ取り込み済みです（正本はADR-0023）
• PR #49 でPhase 8 PR-3d（RecordIntegrityIncidentの実行と、壊れたchainの上での監査記録）を実装し、merge commit f787e9bとしてmainへ取り込み済みです（既知violationの上でだけincident recordの投稿を許す規則、IncidentRequired outcomeとrecord_incident()、IncidentPayloadPort、Issue #50のincident採番欠陥の修正を含む。正本はADR-0024。これでPhase 8が完了し、#13はcloseしました）
• PR #53 で、coder / reviewerへClaude Code・Codexを独立設定する追加案（D-032。2026-09-15にIssue #52の合意recordでDecided、PR #73 / #76で正本へ反映）と横断受入条件AC-RP-NNを計画へ反映し、merge commit 2fa86adとしてmainへ取り込み済みです（Issue #52で追跡。合意済みbaselineは置き換えません）
• PR #54 で#52 PR-B1（role別provider設定のcodecとadapter事前検証契約）を実装し、merge commit a6f1a16としてmainへ取り込み済みです（正本はADR-0025）
• PR #55 で#52 PR-B2（role設定の永続化とruntimeへのbinding）を実装し、merge commit f053d74としてmainへ取り込み済みです（正本はADR-0026。native adapterは未実装）
• PR #56 でPhase 9の最初のPR（reviewer用の独立checkout）を実装し、merge commit 102953dとしてmainへ取り込み済みです（git clone --no-localによる独立clone、exact SHAへのdetached checkout、remote削除とalternates不在の検証、dirty観測つき破棄。Codexは起動しません）
• PR #57 でPhase 9のcanary harness第1段階（専用CODEX_HOMEと固定argvの純粋builder）を実装し、merge commit 17a2ed5としてmainへ取り込み済みです（[permissions] profileのみで構成、隔離checkoutのuntrusted固定、Codex固有の危険引数の拒否。sandbox強制のpreflightと起動前fail closedは次のprocess facade PRの責務）
• src/claude_code_codex_review_loop/にはC-01（domain/）、C-02（schema/）、C-03（process/）、C-04（policy/）、C-05（transport/）、C-06（identity/）、C-07（state/）、C-08（workflow/とruntime/）の実装と、#52の設定契約（runtime/agent_*.py）、C-09の一部（runtime/checkout.py / runtime/codex_canary.py）があります。C-10以降は未着手です

Next actions

実装順序の正本はimplementation plan Section 8です。

• 本repositoryで親roadmap Issue #2を発行する
• 設計文書から親roadmap Issue #2を参照する（PR #3）
• docs/plans/implementation-plan.mdを作成する（PR #4、merge commit 5f8955f）
• agreed target experienceをtechnical componentとdependencyへ分解する（C-01〜C-15）
• docs/architecture/README.mdをindex化し、docs/architecture/overview.mdを新設する
• 実装子Issueを発行し、このIssueから参照する（#5〜#22）
• dependency順に小さなPRで実装する

Component分解の対象

implementation plan Section 4でC-01〜C-15として定義済みです。Section 8のPhase 0〜17が実装単位で、各Phaseを子Issueとします。

• #5 Phase 0 基盤と品質ゲート（PR #24 60dd1e3 / PR #25 a969f63、ADR-0003）
• #6 Phase 1 C-01 domain state machine（計画PR #26 da532ae / 実装PR #27 7ce0e35 / 欠陥修正PR #41 330db76、ADR-0016）
• #7 Phase 2 C-02 protocol schemaとcheckpoint envelope（PR #28 60ebfd2、ADR-0004）
• #8 Phase 3 C-03 process abstraction（PR #29 32901cc、ADR-0005）
• #9 Phase 4 C-04 security policy（PR #30 66615b4、ADR-0006）
• #10 Phase 5 C-05 GitHub transport（PR #31 53c004f、ADR-0007）
• #11 Phase 6 C-06 canonical record検証とcredential隔離（実装完了。PR #32 8bee105 / PR #33 103e495、ADR-0008 / ADR-0009。AC-C06-03の残件をC-09へ引き継ぐためopen）
• #12 Phase 7 C-07 resume（PR #34 2faecc7 / PR #35 176986c / PR #36 ef43b93 / PR #37 a143377、ADR-0010 / 0011 / 0012 / 0013。AC-C07-04はPhase 14 #19）
• #13 Phase 8 C-08 active host protocolとstep engine（PR #38 9e8d711 / #39 5de4467 / #42 fbc5a22 / #43 148427e / #44 60541ea / #45 1676f32 / #46 aa2b6f6 / #47 677ce3a / #48 d567df6 / #49 f787e9b、ADR-0014 / 0015 / 0017 / 0018 / 0019 / 0020 / 0021 / 0022 / 0023 / 0024。欠陥修正PR #41 330db76（ADR-0016）を含む）
• #14 Phase 9 C-09 Codex fresh runtimeと隔離checkout（進行中。PR #56 102953d / #57 17a2ed5 / #61 / #62 / #67 / #68 / #69 / #70 / #71 / #72 / #74 / #75 / #77 / #78 / #80 / #81 / #82 / #83 / #84。checkout・canary harness・preflight・起動facade・prompt fence・head binding・reviewer turn adapter・advertised headの再観測・ADR-0031（Accepted、2026-09-15）の認証材料供給（keyring + 固定home、auth gate、auth-setup、credential probe）まで実装済み。D-032 / D-033はDecided。残りはVMでのnetwork境界検証（ユーザー操作）、auth-setupの実行とcredential-free / real-auth canary、C-10へのport接続）
• #15 Phase 10 C-10 PR mode review loop（dogfooding開始）
• #16 Phase 11 C-11 decision / clarification / follow-up
• #17 Phase 12 C-12 qualificationとfinal reporter
• #18 Phase 13 C-13 human merge gate
• #19 Phase 14 C-07 retention、migration、salvage
• #20 Phase 15 C-14 Issue modeとhandoff
• #21 Phase 16 C-15 Plugin配布と任意wrapper
• #22 Phase 17 release acceptance（S-1〜S-9）

MVP boundary

初回releaseはPR modeとIssue modeの両方の受入条件を満たしてから提供します（D-016）。詳細はSection 13を参照してください。

含めるもの（抜粋）: 手動起動のPR / Issue mode、version付きClaude Code Plugin、install済みController CLI、fresh Codex reviewerと隔離checkout、review→fix→re-reviewの最大round、head SHA binding、local test gateとGitHub CI確認、bounded CI waitとWAITING_CI、cancel / timeout / resume、final reporterとREADY_FOR_HUMAN_MERGE対話gate、明示承認後のgated mergeとMERGED確認、Linux/SSHのtmux継続wrapper、artifact retentionとcleanup

含めないもの: PR自動検知 / watcher / webhook / label trigger、対話型agent TUIへのキー入力注入、既存Codex対話sessionのreviewer再利用、明示承認のない無人auto-mergeとGitHub auto-merge予約、deploy・本番操作、独自daemonや常駐orchestrator、ControllerのMCP server実装・配布

未確定事項

いずれもPhase内で決定する技術判断です（implementation plan Section 10）。ユーザー判断待ちの事項はありません。

• HOST_ACTIONの種類はPhase 8 PR-1で確定（C-01のHostAction 6値。schema v2、ADR-0014）。残るのは粒度の検証（R-04）で、fake GitHub + fake hostの1 roundをPhase 8 PR-3、実PRのdry-runをPhase 10で行う
• clarification result 5値とC-01 eventの対応（Phase 11）
• Plugin / CLI protocol versionの表現形式と互換range（Phase 16）

運用ルール

• このIssueをroadmapとして維持し、子Issueはここから参照します
• target behaviorに影響する決定はtarget experienceのdecision logへD-NNNとして追記します
• 参考実装からコードを選択移植する場合は、対象file、source commit、理由、適用license、移植後testを、その移植PRへ個別に記録します（ADR-0002）
• 外部repositoryのIssue / PR番号、commit SHA、repository識別子を正式な設計根拠として参照しません

Read docs/plans/implementation-plan.md Section 8 and follow the dependency-ordered child issues #14–#22. For the current Phase 9 work, start with src/claude_code_codex_review_loop/runtime/checkout.py and codex_canary.py, then use the C-09 issue to identify remaining acceptance checks. Done means the selected phase's stated acceptance conditions are met and its tests and review evidence are complete.