review 運用

対象読者と目的

この文書は、review workflow を実行する人と、review-orchestrator、review skill、artifact contract を保守する人を対象にする。目的は、通常の review 手順と、失敗時に確認する state、artifact、recovery の境界を分けて示すことにある。

Issue 作成から PR 作成後の確認までの skill の使い分けと主要引数は Issue workflow skill guide を参照する。

通常経路

以下は Issue 実装に伴う review の通常経路である。Issue に紐づかない PR / local diff の review では Issue 専用の claim、readiness、implementation preflight、task ledger、readiness checkpoint、drift-check は要求しない。対象、review mode、reviewer、validation profile を確定し、multi-review prerequisites を確認してから、PR target または local target の multi-review run、finding の収束、必要な CI / E2E の確認へ進む。

1. インストールと multi-review prerequisites を確認する。
2. Issue 作業では Issue claim gate と Issue implementation readiness gate を通す。
3. Issue 作業で requested review mode が auto の場合は review-orchestrator issue review-profile-plan を実行し、resolved review mode、agent、GitHub reviewer、loop budget を後続 gate へ渡す。
4. Issue 作業で local reviewer が必要な場合は review-orchestrator issue capability-preflight を実行する。その後、review-orchestrator issue implementation-preflight で claim / readiness / grill / capability の結果を集約する。review profile artifact で local reviewer が不要だと確認して capability preflight を省略した場合だけ、capability gate を not_applicable として渡す。
5. E2E evaluator と、resolved mode が off でない場合の E2E workflow gate を通す。auto の docs-only 早期 skip は省略理由を記録する。
6. implementation preflight が status: "success"、decision: "proceed"、next_required_action: "implement" を返し、E2E decision も解決済みの時だけ branch / worktree を確定する。コード編集前に review-orchestrator issue task-ledger で task ledger と durable workflow state を作成し、--check で ledger の形式を検証する。
7. 初回の file discovery または最初の failing test 作成後に review-orchestrator issue readiness-checkpoint を実行する。継続を許可しない場合は next_required_action に従い、ledger 作成、ユーザー確認、brief 更新、Issue 分割、spike、Issue 修正へ戻る。
8. 実装後の readiness checkpoint と通常 validation を通し、差分と検証結果を確定する。requested review mode が auto の場合は observed diff で profile を再評価し、risk が上がった時は escalation する。
9. 標準変更では PR 前 simplify を実行し、finding があれば修正して readiness checkpoint と validation から再実行する。implementation brief と observed change stats が trivial skip 条件を満たす場合だけ、省略または 1 subagent に縮退する。resolved review mode が on の場合は、外側の simplify を軽量化し、multi-review 内の final broad / full simplify coverage に一本化してよい。どちらの縮退でも skip 理由と covered-by evidence を artifact に残す。
10. resolved E2E mode が pre-review|both の場合は pre-review E2E gate を実行する。
11. pre-review commit を作成し、working tree が clean であることを確認する。
12. resolved review mode に従い、simplify は追加 local reviewer を起動せず、once は one-shot reviewer、on は pre-review commit を target に PR 前 local multi-review を実行する。once の finding 修正後は readiness checkpoint、通常 validation、PR 前 simplify、必要な pre-review E2E、追加 commit、clean tree、one-shot 再実行を有限回で収束させる。on の finding は action log へ記録し、修正、readiness checkpoint、通常 validation、追加 commit、clean tree 確認、再レビューを required action がなくなるまで繰り返す。
13. push を完了し、pr=create|draft では PR を作成する。pr=none は local target の evidence を使う。
14. PR 作成後、Issue が「変更してはいけない契約」と「受け入れ条件」を持つ三層形式の場合は drift-check を実行し、unmet を収束させる。pr=none ではこの手順をスキップする。
15. resolved review mode が on で PR を作成した場合は PR target の review-orchestrator multi-review run を実行する。PR 前 local phase と head、normalized reviewer job set、validation profile、task context、static prompt config digest が一致し、未処理 required action、timeout、format failure がない場合だけ --with-history で correctness coverage を再利用し、それ以外は local reviewer を再実行する。PR target では CI、conflict、GitHub reviewer の request / wait、thread drain、latest head も評価する。
16. resolved review mode が simplify|once で PR を作成した場合は、resolved GitHub reviewer selector が none でなければ、指定された reviewer の request / wait gate を実行する。
17. review evidence と report で required action を確認し、finding と review thread を収束させる。
18. pr=create|draft では CI、resolved E2E mode が final|both の場合の final E2E、PR 本文を更新する。pr=none では CI と PR 本文更新を要求せず、必要な final E2E だけを実行する。最後に durable workflow state の完了条件を確認する。

通常経路で止まった場合は degraded mode から、approval failure、transport failure、CI follow-up、E2E failure を切り分ける。

Source of truth

• CLI の option と stdout JSON: review-orchestrator --help と各 subcommand の --help
• Issue workflow の state transition: docs/workflow-contracts/issue-workflows.json
• review の判定根拠: multi-review-events.jsonl、multi-review-evidence.json、run artifacts
• 日常運用の recovery: durable workflow dogfood runbook と degraded mode

review-orchestrator は multi-review / adversarial-review の Go orchestration に使う CLI である。review 系 skill の shell script は互換用 shim として維持し、引数検証、lock、成果物生成、per-agent timeout、prompt / argv 生成、agent runner は Go 側で扱う。

review-orchestrator

review-orchestrator は multi-review / adversarial-review の実行本体であり、次の責務を持つ。

• PR 解決
• Issue 作業開始前の claim / ProjectV2 準備
• .multi-review.json の探索と検証
• work-dir / lock / review history の管理
• local reviewer job の起動
• 外側 Agent が保存した simplify artifact の取り込み
• Copilot bot review request / wait / summary 生成
• inline review thread の reply / resolve / close
• adversarial review prompt の生成
• agent team issue workflow の runtime capability probe

Claude Code runtime で simplify-reviewer subagent を使う場合、外側 Agent は prompt と出力を work-dir に保存し、 review-orchestrator multi-review ingest-artifact で取り込む。Go 側が JSONL finding、NO FINDINGS、 parse failure を event log / gate / report に反映するため、skill 本体では件数照合や JSONL parse を行わない。 simplify=auto の broad simplify source は claude-simplify / codex-simplify / copilot-simplify を使う。 simplify=full の観点別 source は claude-simplify-code-reuse / claude-simplify-quality / claude-simplify-efficiency のように runtime と観点を含める。どちらも ingest と report で受け入れる。

external AI policy evidence

review / validation 系 skill が Codex CLI、Claude Code、GitHub Copilot CLI、または同一 Agent の別 context に diff や Issue context を渡す場合は、transport 起動前に ExternalAIInvocationDescriptor 相当の evidence を残す。 最低限、workflow、caller_runtime、target_agent、transport、data_classes、tool_modes を記録する。 data_classes は issue_context、uncommitted_diff、pr_diff、repo_metadata、review_history など送信する情報を分ける。 tool_modes は read_only_review、validation、planning など呼び出し先に許す操作分類を分ける。

approval_required=true で許可がない場合は approval_blocked として transport を開始しない。 transport 起動後の timeout、invalid output、artifact missing、parse failure、cleanup failure、CLI exit failure は transport_failure として扱い、approval failure と混ぜない。 agents=copilot は local GitHub Copilot CLI reviewer であり、GitHub 上の Copilot bot review coverage ではない。 Copilot bot review request / wait / summary は PR target の platform review evidence として別に記録し、target_agent=copilot の approval grant と同一視しない。

internal/agentruntime の external AI helper は、policy 判定、external-ai-approval.v1 artifact、required allow rule の表示を workflow 横断で揃える共通境界である。 workflow 実装は、外部 AI transport を起動する前に exact descriptor を DecideExternalAIApproval へ渡し、許可がない場合は NewExternalAIApprovalArtifact / WriteExternalAIApprovalArtifact と FormatExternalAIApprovalRequiredMessage で approval_blocked と required rule を残してから停止する。 この artifact / stdout を、timeout、subagent unavailable、CLI exit failure など transport 起動後の失敗の代替証跡として使わない。 外部 AI unavailable、rate limit、approval blocked、transport failure で止まった時の手動続行手順は degraded mode を入口にする。

Agent activity decisions

Agent が workflow state、completion、effect の提案を返す場合、自然言語 summary を判定根拠にしない。 control output は agent-activity-decision.v1 の typed decision として扱い、variant、state_version、based_on_event_seq、evidence claim、recovery proposal を program side が検証する。 variant は completed / continue / need more context / recoverable deviation / blocked / unsafe / cannot decide / unknown を区別する。 state_version または based_on_event_seq が現在の state と合わない decision は stale として拒否し、invalid JSON、unknown field、incompatible version、timeout、no response、refusal も no findings や success に変換しない。 evidence claim の意味判定と recovery operation の許可判定は別 gate に委譲し、decision envelope の受理だけで GitHub mutation や filesystem mutation を実行しない。 Issue creation flow の resume では review-orchestrator issue resume-create --workflow-kind <kind> --workflow-id <id> --decision-file <agent-activity-decision.json> を使う。 この command は stable workflow state を load し、state_version: "<workflow_id>:<state_revision>" と based_on_event_seq の完全一致を ValidateAgentActivityDecision で確認したうえで、ValidateRecoveryProposal による expected version / terminal / allowed operation 検証を通す。 stale_state_version、stale_event_seq、future_event_seq、terminal_state は dispatch せず修正対象の proposal / decision として返す。 unsafe、cannot_decide、unknown などの非対応 decision variant は recovery proposal を含んでいても unsupported_agent_decision_variant として止める。 need_more_context は request_user_input だけを dispatch 対象にし、variant は対応済みでも operation との組み合わせが合わない場合は unsupported_variant_operation_combination / revise_recovery_proposal として止める。 first slice で dispatch できる recovery operation は既存定数の retry_activity、recollect_context、request_user_input だけで、typed decision の受理だけでは外部 effect を起動しない。 retry_activity は issue create outcome が succeeded または bound として state に記録済みの場合だけ dispatch し、unknown や未確定 outcome では manual_confirmation_required で停止する。

report / handoff loop run

review-orchestrator loop run は Loop Engineering の state artifact entrypoint である。 report profile では Issue / PR / durable workflow state / acceptance matrix / docs ref を read-only input として受け取り、human-readable report と loop-state.v1 を出力する。 handoff profile では Issue / PR / docs input から既存 workflow family への handoff / resume command を loop-state.v1 の child workflow に残す。workflow state や acceptance matrix は evidence input であり、別 workflow への resume command へ変換しない。downstream workflow は自動起動しない。 旧 org-l1 は report、旧 org-l2 は handoff の互換 alias としてだけ扱い、新規 state / result では短い profile 名を使う。

review-orchestrator --repo TomoakiMizuno/agent-dotfiles loop run \
  --profile report \
  --scope daily \
  --issue 865 \
  --pr-ref 123 \
  --doc docs/skills/loop-engineering.md \
  --acceptance-matrix docs/workflow-contracts/durable-acceptance-matrix.json \
  --out-dir tmp/loop/report-daily

report の non-goal は GitHub mutation と repository mutation である。 この command は Issue 作成、PR 作成、branch 作成、commit、push、merge、下流 workflow dispatch を実行しない。 候補 work item の次 action は report / loop-state.v1 に残し、人間または上位 workflow が別 entrypoint を明示して実行する。 handoff の publication boundary は draft PR、review、E2E、PR body update までであり、non-draft PR creation、merge、auto-merge、required check bypass を要求する resume command は loop-state.v1 validation で拒否する。

durable workflow state root

repo / worktree 配下の tmp/ を workflow state の durability boundary にしない。 default root は ${XDG_STATE_HOME:-$HOME/.local/state}/agent-dotfiles/workflows で、必要な場合だけ review-orchestrator workflow-state ... --root <path> で override する。 state path は workflow kind / workflow ID と repo identity から解決し、repo clone path の移動だけで別 workflow と誤認しない。 state envelope は workflow-state.v1 として、workflow kind / ID / cycle ID、state revision、latest event sequence、requested config、policy revision、phase / status、blocked reason / resume condition、obligation、evidence reference、effect intent / outcome、recovery proposal、artifact reference、producer / contract version、created / updated timestamp、migration history を持つ。 stable state は artifact reference と digest / status を保存し、prompt 全文や diff 全文を無制限に保存しない。 store API の state transition は create、append / compare-and-swap、load、list、inspect、migrate、prune として扱う。

file-backed store は atomic rename で更新し、append / compare-and-swap は expected revision による update として扱う。 stale writer は version conflict として reject し、future schema は unsupported_schema_version として block する。 expected revision による compare-and-swap で stale writer を reject する。 legacy schema の migration は transactional に current schema へ上げ、失敗時は元 state を失わない。 artifact が先に消えている場合は evidence success に丸めない。 reference status を missing / stale として残す。

review-orchestrator workflow-state list は stable root の state 一覧を返し、workflow-state inspect --kind <kind> --workflow-id <id> は new process から resume 条件を確認するための state を返す。 複数 repo が同じ stable root を共有する場合は、--repo-remote と --repo-common-dir で repo identity を指定して scope を固定する。 store に記録された workflow state は、repo tmp/ cleanup や linked worktree 削除後も inspect で resume 条件を確認できる。 workflow-state prune は explicit command であり、active、waiting_input、blocked、unknown は削除しない。 active / waiting_input / blocked / unknown は prune しない。 terminal state (completed / failed / canceled) だけが prune 対象で、--dry-run と --reason を stdout JSON に残す。 terminal state と non-terminal state が混在する場合、terminal state の削除結果と skipped state を stdout JSON に残しつつ、exit code は non-zero にする。 background automatic deletion は導入しない。

日常運用では durable workflow dogfood runbook に従い、自然言語 summary ではなく workflow state、evidence、effect outcome、acceptance matrix への feedback を確認する。

Incident replay / model eval separation

Durable workflow の regression は、production artifact 全体や report 文面 snapshot ではなく、最小 event / state fixture を replay して固定する。 internal/revieworchestrator/multireview/incident_replay_test.go は #953、#946、#952 相当の incident seed と、fake Agent decision、effect idempotency、recovery proposal の property を deterministic Go test として扱う。 この harness は外部 AI、GitHub API、network、host-wide state を呼ばず、replay 時に external effect を再実行しないことを確認する。

実モデル scenario eval は通常 CI から分離する。eval を追加する場合は、task success、false completion、invariant violation、recovery success、unclassified deviation、human intervention、token / time cost を artifact として記録し、unit test の成功条件や production workflow runtime に混ぜない。

parent-assisted Codex reviewer transport

親 Codex session が subagent を起動し、Go 側は artifact だけを受け取る境界として扱う。 transport ID は parent-assisted-codex-subagent とする。 review-orchestrator の subprocess は親 session の subagent tool surface を直接呼べないため、自然言語 summary を成功証跡にせず、 request artifact、response artifact、ingest-artifact の 3 点で状態を固定する。

request artifact は tmp/multi-review/<run>/ または tmp/review-once/<run>/ 配下に置く。 schema は codex-parent-assisted-reviewer-request.v1、transport は parent-assisted-codex-subagent とし、次の field を持つ。

request artifact に新旧 field が同時にある場合、新規 consumer は expected_output_path / response_path を authoritative として読む。 raw_output_path / response_artifact_path / ingest_command は v1 consumer の移行期間向けに残す optional field であり、 新規 flow の必須入力や source of truth にはしない。

response artifact は同じ run 配下に保存し、schema は codex-parent-assisted-reviewer-response.v1、transport は同じく parent-assisted-codex-subagent とする。schema_version、transport、request_id、run_id、head_sha、 source、request_artifact_path、status、raw_output_path、prompt_path、error、cleanup_status を必須 field とする。 agent_id は親 session から安定して取得できる場合だけ入れる。

response status は次の値に限定する。

取り込み source は correctness が codex-subagent-review / codex-subagent-adversarial、simplify が codex-subagent-simplify-code-reuse / codex-subagent-simplify-quality / codex-subagent-simplify-efficiency。 response が completed の場合だけ、同じ source と raw_output_path を使って review-orchestrator multi-review ingest-artifact へ渡す。multi-review transport では次に実行すべき取り込み command は request artifact ではなく review_job_completed.details.next_commands に残す。unavailable、timeout、 parse_failure、cleanup_failure は Copilot bot や local reviewer success で代替せず、required action として扱う。 review_job_completed.details の response_artifact_path と raw_output_path は既存 viewer / history 互換の legacy key であり、 新規 consumer は request artifact と同じ response_path / expected_output_path を優先する。legacy key は互換維持のため当面残す。

review-orchestrator multi-review run --codex-parent-assisted --agents codex は Codex CLI reviewer を起動せず、 request artifact と ingest_codex_parent_artifacts required action を生成する。既定の agents=codex は従来通り Codex CLI transport のままであり、parent-assisted は明示 opt-in として扱う。 parent-assisted では --simplify auto も broad legacy source ではなく codex-subagent-simplify-code-reuse / codex-subagent-simplify-quality / codex-subagent-simplify-efficiency の 3 request に展開し、report の coverage source もこの 3 source に合わせる。

初期 policy は opt-in のまま継続し、default にはしない。multi-review では review-orchestrator multi-review run --codex-parent-assisted、review-once では review-orchestrator review-once run --transport parent-assisted-codex-subagent を明示した場合だけ使う。 --codex-parent-assisted は multi-review の Codex reviewer を parent-assisted-codex-subagent transport にする opt-in として扱う。 実 Codex parent session で request artifact、response artifact、subagent raw output、 実行した ingest subcommand とその stdout JSON、review-once result artifact または multi-review evidence を残せた場合でも、通常の agents=codex default は codex-cli transport のまま維持する。parent-assisted を default 化する場合は、この proof と運用結果を根拠に別 Issue で扱う。

rate limit 近接検知による自動切替は non-goal とする。安定して機械判定できる limit error の exit code / stderr / JSON field が 実証されるまでは、codex-cli から parent-assisted への自動 fallback を実装しない。 limit error 後 fallback を導入する場合も、trigger と recovery evidence を固定する別 Issue で扱う。

parent-assisted proof は自然言語 summary だけで完了扱いにしない。完了報告や PR 前メモには少なくとも request artifact path、response artifact path、subagent raw output path、実行した ingest subcommand とその stdout JSON を残す。 review-once の場合は result artifact の status と next_required_action、 multi-review の場合は gate / evidence manifest の収束結果も確認する。

通常運用と自動化の default は --simplify auto にする。auto は cost-aware default であり、選択 runtime から 1 runtime を broad simplify source として選ぶ。実行は review loop の最終 run で --final-broad を渡す場合だけ行い、これを full coverage 必須として扱わない。 --simplify full は、公開前の高リスク変更、reviewer 間で判断が割れた変更、または明示的に観点別 coverage が必要な場合だけ使う。 --simplify off や runtime 不在で skip された場合は、report の Simplify coverage に残る coverage_mode=skipped と skip_reason を確認する。skip_reason=simplify_off は意図的な無効化、 skip_reason=no_simplify_runtime_available は実行可能 runtime 不在として扱い、未処理 finding や parse failure がなければ skip 自体を blocker にしない。ただし full coverage が受け入れ条件なら、--simplify full で再実行してから完了判断する。 spawn 後の simplify subagent が prompt を処理せず、bounded wait / cleanup でも収束しない場合は subagent_lifecycle_timeout として扱う。 これは runtime 不在、intentional skip、reviewer artifact の final timeout、JSONL parse failure のいずれでもない。coverage を成功扱いせず、 timeout した reviewer、agent id、session artifact path、fallback / stop 判断、再実行した検証コマンドを report / evidence / action log に残せる形で記録する。

auto では correctness finding が残る run の simplify は skip_reason=correctness_findings_present で cost 抑制として skip する。 correctness finding が収束過程で残ったまま review loop を終える場合でも、コメント品質観点を含む broad simplify を最終 run で必ず一度評価するため、 review loop の最終 run でだけ review-orchestrator multi-review run --final-broad を渡す。--final-broad が立つ run では correctness_findings_present による simplify skip だけを解除し、broad simplify を実行して coverage_mode=broad を記録する。 conflict_required / validation_failed / docs_only / test_only / correctness_format_failure / correctness_reviewer_timeout による skip は --final-broad でも従来どおり維持する。中間 run には --final-broad を渡さず、従来どおり skip させる。

PR 作成前の local multi-review は、実装 workflow では通常検証、PR 前 simplify、必要な pre-review E2E gate が収束した後の pre-review commit を対象 HEAD とする。 pre-review commit 後は git diff --exit-code と git status --porcelain で working tree が clean であることを確認し、dirty / 未追跡が残る場合は local reviewer へ進まない。 直接の multi-review local / review-only local は明示 local diff review の entrypoint であり、uncommitted diff を扱える standalone target として分ける。 fix-github-issue / implement-from-plan から reviewer を起動する場合、task-context-file は review-orchestrator --repo OWNER/REPO issue task-ledger --check または review-orchestrator --repo OWNER/REPO plan task-ledger --check を通った ledger を反映する。finding 対応後の rerun scope は checked ledger と action log から targeted / broader を選ぶが、loop budget や enforcement は別 contract の責務として扱う。

PR 作成前の local multi-review の履歴を PR 作成後の target へ引き継ぐ場合は、PR 側の run で review-orchestrator --pr <PR> multi-review run --with-history <local-work-dir> を明示する。 この handoff は指定された work-dir の local reviewer artifact、event log、rejected.txt、 structured finding action、run metadata だけを current work-dir へ取り込み、古い unrelated run は自動探索しない。 shared context には prior action decision が untrusted history として入り、report の timeline には local phase と PR phase が続けて表示される。

multi-review の判断根拠は次の責務で読む。

learning-candidates.v1 は、run 結果を次の skill / docs / validation profile / fixture / contract / matrix / runbook 改善へ渡すための handoff artifact である。 候補は multi-review-events.jsonl から再生成可能な high-confidence signal に限定し、auto_apply_allowed=false と requires_human_approval=true を既定にする。 この artifact は改善候補を見える化するだけで、skill、memory、docs、validation profile、fixture を自動編集しない。 multi-review-report.md と HTML report は learning-candidates.json の path と候補件数を表示する。

最小 schema:

{
  "schema_version": "learning-candidates.v1",
  "source_workflow": "multi-review",
  "summary": {
    "candidate_count": 1,
    "requires_human_approval_count": 1,
    "destination_counts": {
      "fixture": 1
    }
  },
  "candidates": [
    {
      "id": "lc-example",
      "source_workflow": "multi-review",
      "source_workflow_id": "run-1",
      "workflow_family": "review",
      "source_artifact_ref": "multi-review-events.jsonl#sequence=3",
      "repro_event_ref": "multi-review-events.jsonl#sequence=3",
      "source_run_id": "run-1",
      "source_event_type": "action_recorded",
      "source_reviewer": "codex-review",
      "kind": "fixture_candidate",
      "priority": "medium",
      "suggested_destination": "fixture",
      "recommended_targets": ["internal/foo.go"],
      "evidence": ["decision: fixed", "finding: boundary case"],
      "auto_apply_allowed": false,
      "requires_human_approval": true,
      "fixture_candidate": {
        "source_path": "internal/foo.go",
        "summary": "boundary case"
      }
    }
  ]
}

pause / per-agent-timeout / quiescence は、stdout JSON の durations と duration_sources、report の Runtime options、evidence の runtime_options で effective value と default|explicit を確認する。 呼び出し側 Agent は、ユーザー未指定の timeout 系 option を explicit flag として補完しない。未指定時の per-agent-timeout は review-orchestrator が effective pause から正規化し、source は default のまま記録する。

reviewer job の *.status=timeout は実行開始時に置かれる sentinel であり、最終 timeout の証跡ではない。 最終 timeout は review_job_completed.timed_out=true、exit status 124、または evidence の artifacts.status_finality=final_timeout で判断する。 artifacts.status_finality=running_sentinel の場合は、orchestrator.done、stdout JSON、final report / evidence の生成を待つ。

呼び出し側 Agent の最終報告項目は claude/skills/multi-review/SKILL.md の完了前チェックに従う。 --work-dir 未指定時の default work-dir は repo root 配下の tmp/multi-review/ になり、対象 repo の local exclude に /tmp/multi-review/ がなければ追加される。

review-orchestrator multi-review ingest-artifact \
  --work-dir tmp/multi-review/owner-repo-pr-123 \
  --run-id run-20260514 \
  --head-sha abc123 \
  --source claude-simplify-quality \
  --prompt-path tmp/multi-review/owner-repo-pr-123/claude-simplify-quality-prompt.txt \
  --output-path tmp/multi-review/owner-repo-pr-123/claude-simplify-quality.out

claude/skills/multi-review/scripts/run.sh と claude/skills/adversarial-review/scripts/*.sh は旧 entrypoint 互換の shim として残す。実処理は review-orchestrator に寄せる。

agent team capability probe

複数 Issue を coordinator / worker で処理する agent team workflow は、実装前に native worker lifecycle を probe する。 contract、status model、artifact schema、後続 Issue 起票条件は docs/agent-team-issue-workflow-contract.md に固定する。

review-orchestrator agent-team probe --runtime all
review-orchestrator agent-team probe --runtime claude --live --work-dir tmp/agent-team/claude-live-probe

default probe は static / non-destructive で、Codex / Claude の command surface と protocol surface だけを確認する。 --live は opt-in で、Claude の safe no-op background worker を tmp workspace で起動できる場合だけ lifecycle を確認する。 supported は live worker 起動、status 取得、result artifact 回収、cleanup まで確認できた場合だけ返す。 Claude の background start surface が現在の CLI に無い場合も probe 自体は JSON artifact を返し、runtime を unsupported として理由を記録する。 static probe で surface が見えた runtime は partial とし、queue runner や runtime adapter 実装 Issue を起票する根拠にしない。

Issue claim gate

Issue を実装対象として扱う skill は、Issue 本文分析や実装に入る前に reusable gate を通す。 現在の呼び出し元は fix-github-issue。

command details と stdout JSON / exit code の判定契約は claude/skills/github-issue-prepare/SKILL.md に集約し、 呼び出し元 skill 側では blocked 時に branch 作成、実装、PR 作成、multi-review を開始しないことだけを明示する。

Issue implementation readiness gate

claim gate が proceed になった後、実装開始可否は review-orchestrator issue readiness で機械的に判定できる。 contract、brief JSON schema、result JSON schema、decision boundary、path validation scope は docs/implementation-readiness-contract.md に固定する。

review-orchestrator --repo TomoakiMizuno/agent-dotfiles issue readiness \
  --issue <number-or-url> \
  --brief tmp/fix-github-issue/implementation-brief-<issue>.json

stdout JSON が現在の実行結果の authoritative source で、artifact_path は再開や handoff 用の保存先である。 Agent は validation_commands の command 文字列から path を shell parse せず、brief / handoff / observed artifact 内の path field だけを検証対象にする。

Issue post-create availability

Issue 作成直後の metadata 整備は review-orchestrator issue post-create で行う。post-create は assignee を設定しない。 作業開始時の assignee / ProjectV2 Status 更新は review-orchestrator issue prepare の責務として分ける。

review-orchestrator --repo TomoakiMizuno/agent-dotfiles issue post-create --issue <number-or-url> --type task

2026-05-18 に TomoakiMizuno/agent-dotfiles の Issue #354 で実測した結果は次の通り。

• 実行コマンド: review-orchestrator --repo TomoakiMizuno/agent-dotfiles issue post-create --issue 354 --type task
• 対象 repo: TomoakiMizuno/agent-dotfiles
• exit code: 0
• status: success
• actions: []
• project_discovery.action: skipped
• project_discovery.reason: no_repository_projects
• projects: []
• type.requested: task
• type.desired: Task
• type.action: skipped
• type.reason: issue_type_unavailable
• next_required_action: proceed

この repo は user repo であり、GitHub の Issue Types は organization API で提供されるため、Issue Type 候補は取得しない。 その結果、issue_type_unavailable は正常系の unavailable skip として扱い、Issue 作成後処理全体は success / proceed で完了する。 repo-linked ProjectV2 も存在しないため project_discovery.action は skipped、project_discovery.reason は no_repository_projects になり、projects は空配列、Project item 追加 action は発生しない。

ProjectV2 の作成や repository link は issue post-create では行わない。必要な運用だけが明示的に次の command を呼ぶ。

review-orchestrator --repo <owner>/<repo> project ensure --title "<project-title>" --link-repo

project ensure は owner / repo / title / repository link の有無を input として受け取り、既存 Project、作成、repo link、権限不足、duplicate を stdout JSON と exit code で返す。Project が見つからないことを理由に、Issue 作成 skill や AI Agent が ad-hoc な gh project create を実行してはならない。

unavailable skip と API error は次の基準で分ける。

organization repo の success path は、この repo では実機検証していない。公式 docs 上は Issue Types は organization REST API GET /orgs/{org}/issue-types で取得し、 Projects V2 では GraphQL API の addProjectV2ItemById で item を追加してから updateProjectV2ItemFieldValue で Status などの field を更新する。 ローカル unit test では Project item 追加、Issue Type 設定、silent drop、API error を test double で固定しているが、 org repo での実 mutation は未検証 capability として扱う。 後続で org repo 検証が可能になった場合は、この Issue 群を reopen せずフォローアップ Issue で扱う。

インストール

make install は agent-dotfiles、review-orchestrator、agchat をまとめてインストールする。

make install

リポジトリを clone せずに入れる場合:

go install github.com/TomoakiMizuno/agent-dotfiles/cmd/agent-dotfiles@latest
go install github.com/TomoakiMizuno/agent-dotfiles/cmd/review-orchestrator@latest
go install github.com/TomoakiMizuno/agent-dotfiles/cmd/agchat@latest

agent-dotfiles だけが必要であれば 1 行目のみで足りる。review-orchestrator は multi-review / adversarial-review の実行本体である。agchat は installed agmsg scripts を短く呼ぶ会話用 CLI で、multi-review / review-orchestrator を経由しない。

Windows でも go install ./cmd/review-orchestrator でインストールでき、review-orchestrator.exe --help を実行できる。Windows では Unix と同じ process group kill は行わず、multi-review 実行時の完全な子プロセス制御互換性は後続対応とする。

multi-review prerequisites

multi-review 実行前の外部ツールは、実行 target と選択 agent、local validation profile によって変わる。agent-dotfiles doctor は review toolchain の条件付き command を warning として表示するため、新規環境や Windows 環境ではまず次を実行する。

agent-dotfiles doctor --repo /path/to/agent-dotfiles
gh auth status --hostname github.com

agent-dotfiles doctor は条件付き command が見つからない場合も error にはせず warning に留める。JS package manager は npm / yarn / pnpm / bun を個別に表示するため、実際の multi-review で必要かどうかは target、--agents、validation profile を見て判断する。jq は warning に出ても、Go 実装の multi-review 中核 dependency として扱わない。

PR 作成前に local target を使う場合は review-orchestrator multi-review run --local --local-phase pre-pr を使う。 この phase の validation は関連テスト・lintに限定し、GitHub Actions CI や CI 相当の重い fallback は prerequisites に含めない。 --validation-command または明示的な --validation-profile が必須で、未指定なら reviewer 起動前に usage error で停止する。 既存の PR なし standalone local target は従来通り、validation profile や repo からの推定 fallback を許可する。

PR 作成後に Copilot bot thread や local reviewer finding へ対応した修正 commit を push 前 local phase で再レビューする場合は、root --pr <PR> と --local --local-phase pre-pr を併用する。 この形では GitHub 側の既存 Copilot bot unresolved thread を local reviewer 起動前に確認し、local HEAD が PR HEAD より進んでいる場合は push_required_for_copilot_thread_fix と drain_copilot_threads を返す。 通常の修正 commit は review-orchestrator が自動 push しないため、呼び出し側 skill が push 後に thread close / PR target rerun へ進む。

deferred CI follow-up

PR target の CI pending は、review loop を止める required_actions ではなく gates.follow_up_actions の check_ci_later として返る。 この follow-up だけが残る場合、review-orchestrator multi-review run は exit 0 で result_status=follow_up_pending を返し、reviewer finding / Copilot bot thread / local reviewer result の triage は先に進めてよい。 ただし PR ready / 完全完了 / merge-ready とは報告しない。

follow-up action には next_command として次の形の再確認 command が入る。

review-orchestrator multi-review check-ci --work-dir tmp/multi-review/owner-repo-pr-123 --run-id run-1

呼び出し側 Agent は pending follow-up が残る限り、数分後または final report 前に next_command を実行し、結果をユーザー報告に含める。 in-progress CI を待つためだけに reviewer を再実行しない。

結果別の扱い:

CI failure / validation failure を見ないまま完了宣言しないという既存 gate は維持する。 pending だけを review loop blocker から外し、failure が確認された時点で required action として扱う。

Issue / PR 全体コメント

Issue コメントと PR 全体コメントは、次の専用 command から投稿する。

review-orchestrator --repo <owner/repo> post-comment --issue <number-or-url> --body-stdin

本文入力は --body、--body-file、--body-stdin のいずれか 1 つを指定する。–reformat-agent codex|claude|copilot|off で整形担当を選べる。既定値は codex で、off は検査と投稿だけを行う。

投稿前に prose-lint と code fence を除いた入力本文の長さを計測する。本文が 800 字を超えた場合、または prose-lint の文体指紋 4 rule を検出した場合だけ、post-comment が別 context の整形エージェントを起動する。整形後の本文は同じ検査へ戻し、URL、code、見出し、Issue / PR 参照、commit SHA、mention が残っている場合だけ採用する。

検査、整形、再検査、artifact 保存に失敗しても投稿は止めない。整形できない場合は原文を投稿し、post-comment-result.v1 の reformat.status と reason で経路を確認できる。

観測は ${XDG_STATE_HOME:-$HOME/.local/state}/agent-dotfiles/post-comment/ に保存する。post-comment-observation.v1 は整形前後の本文 artifact path と再検査結果を持つが、標準出力には本文 artifact path を出さない。

整形エージェントを起動するには、host-local の agent-runtime.json に呼び出し元 runtime と整形担当の組み合わせを許可する rule が必要になる。次の例は Claude Code から既定の Codex 整形を使う設定である。別の組み合わせでは caller_runtime と target_agent を置き換える。

{
  "external_ai": {
    "approval_policy": [
      {
        "workflow": "post-comment-reformat",
        "caller_runtime": "claude",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["comment_body"],
        "tool_modes": ["reformat"],
        "decision": "allow"
      }
    ]
  }
}

agent-dotfiles doctor は、現在の runtime から既定の Codex 整形を起動する rule があるかを表示する。rule がなくても doctor の結果は error にならず、post-comment も原文で投稿を続ける。host-local の設定は agent-dotfiles の管理・配布対象へ追加しない。

投稿先が PR の場合は、本文の内容にかかわらず投稿前に one-time approval を消費する。approval の scope には PR 番号、本文ハッシュ、pr-comment-review-reply operation が必要になる。GitHub API が失敗した場合は post-comment-result.v1 の status: "error" と non-zero exit を返す。

Claude の PreToolUse hook は、agent-dotfiles hook block-dangerous-commands --post-comment-route で gh issue comment、gh pr comment、代表的な gh api の新規コメント投稿を literal に検出できる場合だけ、この command へ誘導する。変数展開や動的な interpreter payload、読めない script など、投稿を静的に確定できない command は block しない。読める script が shell parse に失敗しても、script 全文の raw 検査で literal な投稿を検出した場合は block する。既存コメントの編集・削除と読み取り操作は対象外である。review thread へ返信のみ行う場合は review-orchestrator reply、返信して resolve する場合は review-orchestrator close-thread を使う。どちらも投稿直前に AI attribution フッターを自動付与する。

multi-review.json

multi-review の agent 別設定は agent-dotfiles import/export の管理 root に含めない。現状の探索順は以下の通り。

1. review-orchestrator multi-review run --config PATH の明示指定
2. リポジトリ root の .multi-review.json
3. カレントディレクトリの .multi-review.json
4. ${XDG_CONFIG_HOME:-$HOME/.config}/agent-dotfiles/multi-review.json

個人環境のデフォルトは dotfiles 側の host profile として ${XDG_CONFIG_HOME:-$HOME/.config}/agent-dotfiles/multi-review.json に置く。repo-local な挙動を固定したいプロジェクトだけ .multi-review.json を置き、agent/model の実験的な引数は --config か XDG config 側に寄せる。Claude MCP policy や Claude transport のように multi-review 以外の workflow からも使う host-local な実行設定は agent-runtime.json に置く。

agent-runtime.json

${XDG_CONFIG_HOME:-$HOME/.config}/agent-dotfiles/agent-runtime.json は、review workflow 全体で共有する host-local な agent 実行設定であり、agent-dotfiles import/export の管理 root に含めない。 現時点では Codex runtime から Claude reviewer を呼ぶ場合の transport selector、Claude MCP policy、人間が開始した GitHub review thread への one-time write approval store を読む。 Claude reviewer transport の default は headless (review-orchestrator claude-headless run、claude --print を使う) であり、direct PTY (review-orchestrator claude-direct run) は --claude-transport direct-pty または明示 subcommand での opt-in とする。review-orchestrator multi-review run / review-orchestrator adversarial run は –claude-transport headless|direct-pty flag を持ち、解決順は CLI 明示値 > agent-runtime.json の claude.transport > default headless とする。transport failure 時は別 transport へ黙って fallback せず、失敗した transport / command / stderr summary / artifact path / 次 action を report / evidence に残し、report の「Claude transport metadata」section で claude_transport=headless と claude_transport=direct-pty を区別できる。 review-orchestrator multi-review run は --claude-mcp が未指定の場合に claude.mcp を読み、さらに無ければ default off とする。workflow から agmsg relay / worker transport は起動しない。 Claude 起動前 fallback 用の判定 helper は review-orchestrator claude-rate-limit decision から利用する。claude.rate_limit_checker.command が未設定の場合、この helper は既存挙動維持のため allow_claude と判定する。実際の Claude 起動経路へこの判定を適用する処理は別 Issue の責務とする。 review-orchestrator reply / resolve / close-thread と direct gh api は、comment が 1 件以上あり全投稿者を bot と確認できた thread だけ承認を不要にする。空 thread、bot 以外の投稿者を含む thread、全投稿者を確認できない thread は承認評価へ戻す。人間由来レビューへの返信に相当する gh pr comment / post-comment も同じ approval を要求する。

direct gh api で bot 免除が効くのは、review thread への返信、resolve、および同一 GraphQL request 内で両者を行う mutation に限る。thread の投稿者取得は数秒の timeout 付きで行い、lookup 失敗と timeout は判定不能として承認評価へ戻す。comment の edit / delete と pull review write は投稿者にかかわらず承認を要求する。

承認が必要な操作を実行する場合は、github.human_review_write_approval_store を設定したうえで、コマンドごとに AGENT_DOTFILES_HUMAN_REVIEW_WRITE_APPROVAL へ scope 付き JSON を渡す。approval は nonce、expires_at、operation、任意の repo / thread_id / comment_id / body_sha256 で照合され、store に記録された nonce は再利用できない。AI classifier は「人間コメントへ書いてよいか」の承認には使わない。 外部 AI Agent へ Issue 文脈や未公開差分を渡す承認 intent も、workflow 横断の host-local runtime policy として external_ai.approval_policy に置く。.multi-review.json は multi-review 専用の reviewer 設定であり、github-issue-validation や Claude / Copilot から Codex を呼ぶ逆方向の承認 intent には使わない。

{
  "claude": {
    "transport": "headless",
    "mcp": "off",
    "opus_fallback_model": "opus",
    "rate_limit_checker": {
      "command": ["review-orchestrator", "claude-rate-limit", "probe"],
      "thresholds": {
        "five_hour": 90,
        "seven_day": 95,
        "seven_day_sonnet": 95
      }
    }
  },
  "github": {
    "human_review_write_approval_store": "~/.local/state/agent-dotfiles/human-review-write-approvals.json"
  },
  "external_ai": {
    "implementation_workflow_guard": {
      "agent": "codex",
      "model": "replace-with-lightweight-model",
      "timeout": "10s",
      "runtimes": {
        "claude": { "agent": "claude", "model": "replace-with-lightweight-claude-model" },
        "codex": { "agent": "codex", "model": "replace-with-lightweight-codex-model" }
      }
    },
    "approval_policy": [
      {
        "workflow": "multi-review",
        "caller_runtime": "codex",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["issue_context", "uncommitted_diff", "pr_metadata", "review_threads", "review_history"],
        "tool_modes": ["read_only_review"],
        "decision": "allow"
      },
      {
        "workflow": "review-only",
        "caller_runtime": "codex",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["issue_context", "uncommitted_diff", "pr_metadata", "review_threads", "review_history"],
        "tool_modes": ["read_only_review"],
        "decision": "allow"
      },
      {
        "workflow": "adversarial-review",
        "caller_runtime": "codex",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["issue_context", "uncommitted_diff", "pr_metadata", "review_threads", "review_history"],
        "tool_modes": ["read_only_review"],
        "decision": "allow"
      },
      {
        "workflow": "multi-review",
        "caller_runtime": "codex",
        "target_agent": "copilot",
        "transport": "cli",
        "data_classes": ["issue_context", "uncommitted_diff", "pr_metadata", "review_threads", "review_history"],
        "tool_modes": ["read_only_review", "github_mcp_server", "web_fetch", "all_urls"],
        "decision": "allow"
      },
      {
        "workflow": "implementation-workflow-guard",
        "caller_runtime": "codex",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["shell_command", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "implementation-workflow-guard",
        "caller_runtime": "claude",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["shell_command", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "implementation-workflow-guard",
        "caller_runtime": "codex",
        "target_agent": "claude",
        "transport": "cli",
        "data_classes": ["shell_command", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "implementation-workflow-guard",
        "caller_runtime": "claude",
        "target_agent": "claude",
        "transport": "cli",
        "data_classes": ["shell_command", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "completion-workflow-guard",
        "caller_runtime": "codex",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["hook_payload", "transcript_excerpt", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "completion-workflow-guard",
        "caller_runtime": "codex",
        "target_agent": "claude",
        "transport": "cli",
        "data_classes": ["hook_payload", "transcript_excerpt", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "completion-workflow-guard",
        "caller_runtime": "claude",
        "target_agent": "claude",
        "transport": "cli",
        "data_classes": ["hook_payload", "transcript_excerpt", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      },
      {
        "workflow": "completion-workflow-guard",
        "caller_runtime": "claude",
        "target_agent": "codex",
        "transport": "cli",
        "data_classes": ["hook_payload", "transcript_excerpt", "repo_metadata"],
        "tool_modes": ["classification"],
        "decision": "allow"
      }
    ]
  }
}

claude.mcp は off|on のみ許可する。優先順位は --claude-mcp 明示、agent-runtime.json の claude.mcp、default off の順。off では Go 側 wrapper が空の strict MCP config を渡し、user-level MCP server を起動しない。on は full user-level MCP が必要な workflow だけで明示する。 claude.transport は headless|direct-pty のみ許可する。優先順位は --claude-transport 明示、agent-runtime.json の claude.transport、default headless の順。headless は claude --print 経路、direct-pty は interactive claude を PTY 付きで起動する経路で、transport failure 時は別 transport へ黙って fallback しない。 github.human_review_write_approval_store は absolute path または ~/ から始まる path を受け付ける。store は human review thread への write approval の消費済み nonce を保存するだけで、承認そのものは AGENT_DOTFILES_HUMAN_REVIEW_WRITE_APPROVAL の JSON で毎回渡す。

external_ai.approval_policy は workflow 実装が preflight で参照する承認 intent の source of truth であり、Codex / Claude / Copilot の provider 認証状態や global permission mode を管理しない。各 rule は次の field を持つ。 Codex reviewer を codex exec で起動する場合も、target_agent: "codex"、transport: "cli"、tool_modes: ["read_only_review"] の外部 AI 呼び出しとして扱い、Issue context や未公開差分を渡す前に同じ preflight を通す。multi-review、review-only、adversarial-review は workflow 名ごとに明示的な allow rule を置く。 external_ai.implementation_workflow_guard は agent-dotfiles hook block-dangerous-commands --implementation-workflow-guard が shell の作業ディレクトリを静的に決められない時だけ使う任意の分類器設定である。 agent は off|codex|claude、model は呼び出す CLI に渡す軽量 model、timeout は Go duration 文字列を指定する。任意の runtimes は key を codex|claude(hook の --agent で渡る呼び出し元 runtime)に限定した object で、value の agent / model / timeout のうち空でない field だけ top-level default を上書きする。呼び出し元 runtime と同じ provider を指定すれば、片方の provider が rate limit の間も他方の runtime は単独で動作できる。実効設定が未設定または off の場合、hook は AI を呼ばず fail-closed で止める。 分類器の CLI 起動は最小設定で行う。claude は --safe-mode(CLAUDE.md / skills / plugins / hooks / MCP を読み込まない)、codex は --ignore-user-config(config.toml の MCP server 等を読み込まない)と --ignore-rules を付け、判定に必要な payload 文字列だけを渡す。 実行時は workflow: "implementation-workflow-guard"、transport: "cli"、data_classes: ["shell_command", "repo_metadata"]、tool_modes: ["classification"] の allow rule が必要で、caller / target の組み合わせごとに明示する。分類器には hook payload の cwd と command 文字列だけを渡し、allow かつ静的に抽出した literal workdir 候補と一致する workdir が返った場合だけ通常の workflow guard 判定へ戻る。

token は小文字化して読み込まれ、空文字や空配列は拒否される。workflow / target_agent / data_classes / tool_modes の値は registry 固定しない。後続 workflow が必要な語彙を docs や Issue contract で定義し、parser は JSON shape と安全な token だけを検証する。

review-orchestrator agent-runtime doctor --format json は host-local agent-runtime.json を読み、review 系 workflow から Codex CLI reviewer を呼ぶための最小 allow rule coverage を検査する。初期版は review-only、multi-review、adversarial-review について、caller_runtime が claude、copilot、unknown、target_agent が codex、transport が cli、tool_modes が ["read_only_review"] の rule 不足を検出する。不足がある場合は stdout JSON の status: "blocked"、next_required_action: "configure_external_ai_approval_policy"、required_policy_rules に追記候補を出し、exit code は 2 とする。明示 block rule が coverage を止めている場合は、追記候補ではなく blocked_policy_rules に該当 rule を出す。coverage が揃っている場合は status: "success"、next_required_action: "proceed" で exit code 0 とする。config parse error や --config の path 不備は exit code 1 とする。この command は検出専用で、host-local file は編集しない。

現在の codex/hooks.json の PermissionRequest hook は Superset / cmux など通知系へイベントを forward する経路であり、外部 AI approval policy の source of truth ではない。Codex hook が machine-readable な approve / block decision を返せることを workflow 側で実証できるまでは、完全自動承認は agent-runtime.json の policy と workflow preflight / wrapper / subcommand の組み合わせで扱う。hook だけで承認できない shell 実行は、通常の Codex sandbox approval または安全に scoped された prefix rule を使い、global な approval_policy 低下や broad shell allow で回避しない。

review-orchestrator claude-rate-limit probe は Claude Code の OAuth token を読み取り、https://api.anthropic.com/api/oauth/usage から現在の usage を取得して checker JSON schema を stdout に出す。macOS では /usr/bin/security find-generic-password -a $USER -s "Claude Code-credentials" -w の JSON から claudeAiOauth.accessToken を読む。non-macOS では ~/.claude/.credentials.json の同じ JSON schema を読む。token refresh、Keychain / credentials file の書き換え、cache 永続化はしない。HTTP request は Bearer 認証ヘッダと anthropic-beta: oauth-2025-04-20 を付け、redirect は許可しない。

review-orchestrator claude-rate-limit decision --model <model> --format json は host-local checker command を実行し、decision、reason、requested_model、fallback_target、observed_limits、thresholds、checker_status を JSON で返す。valid decision は allow_claude、use_opus、use_codex、skip_guard で、checker command missing / non-zero / invalid JSON / required key missing による fail-closed use_codex も exit 0 とする。checker command 未設定時は常に既存挙動維持の allow_claude とし、checker failure は常に use_codex に倒す。non-zero は CLI usage error、config parse 不能、decision JSON を信頼できない内部 error に限定する。

checker command の stable JSON schema は次の形に固定する。used_percentage は required number、resets_at は optional Unix timestamp seconds、overage は optional boolean とする。five_hour と seven_day は required global limit で、sonnet 系 model を要求している場合だけ seven_day_sonnet も required とする。non-sonnet request では seven_day_sonnet 欠落を sonnet_limit_not_applicable として無視する。

{
  "rate_limits": {
    "five_hour": { "used_percentage": 89.1, "resets_at": 1780000000 },
    "seven_day": { "used_percentage": 94.2, "resets_at": 1780000000 },
    "seven_day_sonnet": { "used_percentage": 95.1, "resets_at": 1780000000 }
  },
  "overage": false
}

decision precedence は overage=true、global 5h >= 90、global 7days >= 95 を最優先で use_codex にする。次に sonnet 系 model で seven_day_sonnet >= 95 の場合だけ use_opus にし、fallback target は claude.opus_fallback_model、未指定時は opus とする。claude.opus_fallback_model が sonnet 系 alias の場合は config error として Claude を起動せず use_codex に倒す。CLAUDECODE=1 の caller env では checker command を実行せず skip_guard / reason=claude_code_runtime を返す。

probe が読む Anthropic usage response は five_hour / seven_day / seven_day_sonnet の各 bucket にある utilization と、存在する場合だけ RFC3339 / RFC3339Nano resets_at を checker schema へ写す。seven_day_sonnet が response に無い場合は出力から省略する。overage は取得手段がないため出力しない。token 取得不能、HTTP 401 / 429 / 非 200、decode 失敗、used_percentage 範囲外、存在する resets_at の parse 失敗は probe の non-zero exit と stderr reason になり、decision 側では checker failure として fail-closed use_codex に倒す。

provider billing 設定、host-local 実運用 config への適用はこの repo の責務外とする。usage endpoint の schema が変わった場合は decode 失敗として扱い、agent-dotfiles 側で曖昧 alias を推測で増やさない。

dotfiles との責務境界

包括的な責務境界は README.md の dotfiles との責務境界 を参照する。

review 運用では、agent-dotfiles / review-orchestrator を解決できる shell PATH、個人環境の ${XDG_CONFIG_HOME:-$HOME/.config}/agent-dotfiles/multi-review.json、必要に応じて ${XDG_CONFIG_HOME:-$HOME/.config}/agent-dotfiles/agent-runtime.json を dotfiles 側の host profile として先に用意する。agent-dotfiles 側は review 系 skill と review-orchestrator の配布を扱い、個人ごとの agent 実行設定は import/export の管理 root に含めない。