harness-work

Harness Work

Harness の統合実行スキル。 以下の旧スキルを統合:

• work — Plans.md タスクの実装（スコープ自動判断）
• impl — 機能実装（タスクベース）
• breezing — チームフル自動実行
• parallel-workflows — 並列ワークフロー最適化
• ci — CI 失敗時の復旧

Quick Reference

Execution Mode Auto Selection（フラグなし時の自動判定）

明示的なモードフラグ（--parallel, --breezing, --codex）がない場合、 対象タスク数に応じて最適なモードを自動選択する:

ルール

1. 明示フラグは常にオートモードを上書きする
   • --parallel N → Parallel モード（タスク数に関係なく）
   • --breezing → Breezing モード（タスク数に関係なく）
   • --codex → Codex モード（タスク数に関係なく）
2. --codex は明示時のみ発動。Codex CLI が未インストールの環境があるため、自動選択しない
3. --codex は他モードと組み合わせ可能: --codex --breezing → Codex + Breezing

Execution Backend Selection（実装バックエンド選択）

バックエンド（どのランタイムが実装するか）は、トポロジー（実行モード: solo / parallel / breezing）と直交する。 トポロジーが「何ワーカーで・どう分割して回すか」を決めるのに対し、バックエンドは「実装の手を誰が動かすか」を決める。 この契約は host-neutral であり（spec.md「Execution Backend Contract」）、Codex host から harness を駆動しても Claude Code から駆動しても同じに振る舞う。

解決手順

run 開始時に 1 回だけ解決する。backend 判定は 必ず resolver 経由にし、HARNESS_IMPL_BACKEND env だけを直読みして判定しない:

bash "${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh"

precedence（高い順）: --backend <v> / --cursor / --codex フラグ > HARNESS_IMPL_BACKEND 環境変数 > プロジェクト env.local の同名行 > ユーザー ~/.config/claude-harness/impl-backend.env の同名行 > call-site default。 明示フラグ（--backend / --cursor / --codex）は env / file / default を常に上書きする。プロジェクト設定はユーザースコープを上書きする。

Codex host の --breezing / breezing も配布 plugin では call-site default を変えない。 フラグなしは resolve-impl-backend.sh の結果に従い、未設定時の fallback は claude。 Cursor を既定にしたい環境は HARNESS_IMPL_BACKEND=cursor を env / project env.local / user-scope config に設定する。 明示的に Cursor を使う場合は --backend cursor / --cursor、Codex native subagent worker へ戻す場合は --backend claude を渡す。

モデル名の正本は model-routing.sh。本ドキュメント中の composer-2.5-fast は参照値であり、実解決は bash "${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh" --host cursor --role worker --field model に従う（drift 防止）。

自然言語 backend trigger

ユーザーが composer / コンポーザー / Composer で / composer 2.5 / composer モード と言った場合は、cursor backend 指定として扱う。 これは --cursor と同じ intent だが、backend の確定値は必ず resolve-impl-backend.sh で解決する。 解決時は明示 override として --backend cursor を渡し、env / project / user file / default より優先させる。 Lead は composer を Codex native Worker 内の追加 agent と解釈せず、非 claude backend の規約どおり Worker agent を挟まずに cursor-companion.sh を直接呼ぶ。

role-scoped 制約

バックエンドは role-scoped。解決済みバックエンドを使うのは実装（worker）ロールだけ。 Reviewer と Advisor の両ロールは常に brain（--host claude、Opus）に固定する。 Reviewer を cursor / codex バックエンドに routing しない（実装したバックエンドが自分の出力をレビューしてはならない）。

非 claude バックエンドの self_review ゲート

backend が codex または cursor の場合、worker-report.v1 も self_review 配列も生成されない。 そのため Lead は self_review ゲートをスキップし、Lead の diff レビューを唯一の品質ゲートとする（既存の codex path と同じ扱い）。

cursor バックエンドの banner（委託前に必須）

backend が cursor のとき、Lead は委託前に次の 1 行 banner を必ず出力する:

⚠️ cursor backend: model=composer-2.5-fast / R01-R13 ガードレールは cursor-agent 内部に適用されない / 出力は Lead レビューまで untrusted

cursor の write 委託は専用 .git を持つ worktree 内で実行し、Lead が main へ cherry-pick する（cherry-pick 経路で R01-R13 が適用される）。 ガバナンス詳細は .claude/rules/cursor-cli-only.md を参照。

オプション

Progressive Disclosure

まずこの本文で入口、自動選択、停止条件だけを確認する。 詳細は必要になった時だけ読む。

重要停止条件

• Plans.md が旧フォーマットで DoD / Depends / Status を読めない時は停止する。
• 仕様が実装判断に影響するのに project spec SSOT が見つからない時は、先に仕様正本を作成/更新してから実装する。
• sprint-contract が required なのに ready でない時は実装に進まない。
• critical / major review finding が残っている時は完了にしない。
• テストを弱める、skip する、期待値を実装に合わせて緩める形では解決しない。
• helper script は host project の scripts/ ではなく ${HARNESS_PLUGIN_ROOT}/scripts/ から呼ぶ。
• 複数 Plans.md がある場合は、1 run の中で plan を切り替えない。必要なら --plan NAME を明示して新しい run を開始する。

Token Optimization (v2.1.69+): git 操作を伴わない軽量タスクでは plugin settings の includeGitInstructions: false を有効にして プロンプトトークンを削減できる。

スコープダイアログ（引数なし時）

harness-work
どこまでやりますか?
1) 次のタスク: Plans.md の次の未完了タスク → Solo で実行
2) 全部（推奨）: 残りのタスクをすべて完了 → タスク数で自動モード選択
3) 番号指定: タスク番号を入力（例: 3, 5-7）→ 件数で自動モード選択

引数ありなら即実行（対話スキップ）:

• harness-work all → 全タスク、自動モード選択
• harness-work 3-6 → 4件なので Breezing 自動選択

Effort レベル制御（Opus 4.8 / v2.1.111+）

effort はモデルの推論強度を選ぶ正式なノブ。low(○)/medium(◐)/high(●)/xhigh の 4 段階で、 /effort auto でデフォルトにリセットできる（max は v2.1.72 で廃止、xhigh が後継）。

Opus 4.8 では thinking は既定 off で、effort が推論深度の主レバー（過去のどの Opus より effort の影響が大きい）。 「浅い推論」を観測したら prompt で回避せず effort を上げる。 そのため複雑タスクの強化は free-text marker（旧 ultrathink）を spawn prompt に注入する方式を廃止し、 複雑度スコアから Worker spawn の effort tier を選ぶ方式に統一する。

多要素スコアリング

タスク着手時に以下のスコアを合算する。

effort tier の決め方（注入しない）

スコアから effort tier を escalation signal として決める（ultrathink 等の marker 文字列を spawn prompt に 書かない）。 適用 lever は次の 2 つだけ:

• session /effort: 複雑タスクのバッチに入る前に host が /effort high / /effort xhigh を設定する（session 単位で効く確実な lever）。
• worker frontmatter: agents/worker.md の effort（既定 medium）が floor。CC の Agent / Task spawn API は per-spawn の effort 指定を公開しないため、worker 1 体ごとに effort を上げる機構はない。スコアは worker-report.v1 の task_complexity_note に記録し、Lead が session effort 引き上げの判断材料にする。

breezing モードでも同じロジックを適用する（harness-work が一本化して管理）。

実行モード詳細

Harness helper script root

Harness が同梱する helper script は、作業対象プロジェクトの scripts/ ではなく、必ず plugin bundle root から呼ぶ。

HARNESS_PLUGIN_ROOT="${HARNESS_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-}}"
if [ -z "$HARNESS_PLUGIN_ROOT" ] && [ -n "${CLAUDE_SKILL_DIR:-}" ]; then
  probe="$(cd "${CLAUDE_SKILL_DIR}" && pwd)"
  while [ "$probe" != "/" ] && [ ! -d "$probe/scripts" ]; do
    probe="$(cd "$probe/.." && pwd)"
  done
  [ -d "$probe/scripts" ] && HARNESS_PLUGIN_ROOT="$probe"
fi

以降の node "${HARNESS_PLUGIN_ROOT}/scripts/..." / bash "${HARNESS_PLUGIN_ROOT}/scripts/..." は、この解決済み root を前提にする。

Backend-resolved executor path (Solo / Parallel / Breezing)

Solo / Parallel / Breezing は同じ resolver result から実装 executor を選ぶ。 harness-work 3 --cursor と user/project HARNESS_IMPL_BACKEND=cursor は、1 件タスクでも local Read/Write/Edit/Bash に fall through してはいけない。

resolver_backend_arg = ""
if explicit_backend_value in ["claude", "codex", "cursor"]:
    resolver_backend_arg = "--backend {explicit_backend_value}"
backend = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh\" {resolver_backend_arg}")
if explicit_flag == "--cursor":
    backend = "cursor"
if explicit_flag == "--codex":
    backend = "codex"

if topology in ["solo", "parallel"] and backend in ["cursor", "codex"]:
    BASE_REF = git("rev-parse", "HEAD")
    WT_ID = "{task.number}-$(date +%Y%m%d-%H%M%S)-$"
    worktree_path = ".claude/worktrees/{backend}-{WT_ID}"
    worktree_branch = "{backend}-work/{WT_ID}"
    bash("mkdir -p .claude/worktrees && git worktree add -b {worktree_branch} {worktree_path} {BASE_REF}")
    companion_prompt = "{task prompt}\n\nAfter making changes, create exactly one git commit in this worktree before returning."
    if backend == "cursor":
        companion_output = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worktree_path} \"{companion_prompt}\"")
    else:
        companion_state_file = "{worktree_path}/.claude/state/codex-primary-environment.json"
        companion_output = bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worktree_path} \"{companion_prompt}\"")
    latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
    if backend == "cursor" and git("-C", worktree_path, "status", "--porcelain") != "":
        git("-C", worktree_path, "add", "-A")
        git("-C", worktree_path, "-c", "user.name=cursor-composer", "-c", "user.email=cursor-composer@local", "commit", "--no-verify", "-m", "cursor: delegated change")
        latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
    if latest_commit == BASE_REF:
        raise EscalationError("{backend} companion produced no commit")
    worker_result = {type: "companion-result.v1", baseCommit: BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: worktree_branch, files_changed: git("-C", worktree_path, "diff", "--name-only", "{BASE_REF}..HEAD"), summary: companion_output}
    enter_shared_review_loop(worker_result)
else:
    run_native_solo_or_parallel()

Parallel は task ごとにこの resolver path を適用する。 backend=cursor / codex の場合は native Worker spawn を使わず、task ごとに isolated companion worktree を作成して companion-result.v1 に正規化してから共通 review / cherry-pick loop に入る。

Solo モード（1 件時の自動選択）

1. Plans.md を読み込み、対象タスクを特定
   • Plans.md が存在しない場合: harness-plan create --ci を自動呼び出し → Plans.md を生成して続行
   • ヘッダーに DoD / Depends カラムがない場合: Plans.md が旧フォーマットです。harness-plan create で再生成してください。 → 停止
   • 会話に未記載タスクがある場合: 直前の会話コンテキストから要件を抽出し、Plans.md に cc:TODO で自動追記
     • 抽出ロジック: ユーザー発言からアクション動詞（「〜を追加」「〜を修正」「〜を実装」）を検出
     • 追記時は v2 フォーマット（Task / 内容 / DoD / Depends / Status）に準拠
     • 追記後、ユーザーに「Plans.md に以下を追記しました」と表示（5 秒タイムアウト付きプロンプト、デフォルト: 続行） 1.5. タスク背景確認（30 秒）:
   • タスクの「内容」と「DoD」から 目的（このタスクが解く課題）を 1 行で推論表示
   • git grep / Glob で 影響範囲（変更が及ぶファイル/モジュール）を推論表示
   • 推論に自信がある場合: そのまま実装に進む（フロー遅延なし）
   • 推論に自信がない場合: ユーザーに 1 問だけ確認（「この理解で合っていますか？」） 1.6. 仕様正本 preflight:
   • 既存の project spec SSOT を探す（例: docs/spec/00-project-spec.md, docs/ARCHITECTURE.md, docs/HANDOFF.md, docs/oem/PROJECT_COMPASS.md, docs/specs/）
   • task が product behavior / API / data model / permission / billing / integration / tenant boundary を変える場合、spec がなければ docs/spec/00-project-spec.md を作る
   • spec が古い、または task と矛盾する場合は、実装前に spec を更新する
   • typo / format / dependency bump / docs-only / 動作変更なし refactor は skip 理由を残して続行する
   • Worker / Reviewer へ渡す context には spec_path または spec_skip_reason を含める
2. タスクを cc:WIP に更新
3. TDD フェーズ（[skip:tdd] なし & テストFW存在時）: a. テストファイルを先に作成（Red） b. 失敗を確認 c. bash "${HARNESS_PLUGIN_ROOT}/scripts/log-tdd-red.sh" で .claude/state/tdd-red-log/<task-id>.jsonl に FAIL 証跡を残す。script が利用できない環境では、literal な failing test output を worker-report の self_review evidence に添付する d. --tdd-bypass を使う場合は、HARNESS_TDD_BYPASS=1 と HARNESS_TDD_BYPASS_REASON="<理由>" を明示し、TDD を省略した理由を sprint-contract / worker-report に残す
4. node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" <task-id> で sprint-contract.json を生成
5. Reviewer 観点の追記を bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" で加え、bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" で approved を確認
6. Advisor consult（必要時のみ）:
   • 高リスク task（needs-spike / security-sensitive / state-migration）は、初回実行前に 1 回だけ相談する
   • 同じ原因の失敗が 2 回続いたら、3 回目に入る前に相談する
   • plateau（行き詰まり検知）が PIVOT_REQUIRED を返した時は、ユーザーへ止めて投げる前に 1 回だけ相談する
   • 相談結果は advisor-response.v1 で受け取り、PLAN は進め方の組み替え、CORRECTION は局所修正、STOP は即エスカレーションとして扱う
   • 同じ trigger_hash では 1 回しか相談しない。task ごとの相談回数は最大 3 回
7. backend-resolved executor path でコードを実装（Green）
   • backend=claude: local / native Read/Write/Edit/Bash path で実装
   • backend=cursor / codex: 上記 companion worktree path で実装し、companion-result.v1 を共通 review loop に渡す
8. /simplify で Auto-Refinement（--no-simplify で省略可）
9. 自動レビューステージ（「レビューループ」参照）:
   • Codex exec 優先でレビュー実行 → フォールバックで内部 Reviewer agent
   • sprint-contract.json の reviewer_profile が runtime の場合は bash "${HARNESS_PLUGIN_ROOT}/scripts/run-contract-review-checks.sh" を実行
   • REQUEST_CHANGES の場合: 指摘を元に修正→再レビュー（MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3）
   • APPROVE で次ステップへ。self-check だけでは完了を確定しない
10. bash "${HARNESS_PLUGIN_ROOT}/scripts/write-review-result.sh" で review artifact を正規化して保存（browser profile は --browser-result を渡し、browser_verdict == PENDING_BROWSER の時は static verdict を採用）
11. git commit で自動コミット（--no-commit で省略可）
12. タスクを cc:完了 に更新（commit hash 付与）

• git log --oneline -1 で直近の commit hash（短縮形 7 文字）を取得
• Plans.md の Status を cc:完了 [a1b2c3d] 形式で更新
• commit がない場合（--no-commit 時）は hash なしで cc:完了 のみ

13. リッチ完了報告（Completion Report Output Contract と references/completion-report.md を参照）
14. 失敗時の自動再計画（テスト/CI 失敗時のみ）:
    • テスト実行結果を確認
    • 失敗した場合: 修正タスク案を state に保存し、承認コマンド経由で Plans.md に追加（「失敗タスクの自動再チケット化」参照）
    • 成功した場合: 次タスクへ進む

Parallel モード（2〜3 件時の自動選択 / --parallel N で強制）

[P] マーク付きタスクを N ワーカーで並列実行。 --parallel N で明示指定した場合は、タスク数に関係なくこのモードを使用。 同一ファイルへの書き込みが競合する場合は git worktree で分離。 各 task の実装 executor は Backend-resolved executor path に従う。 --parallel N --cursor、--backend cursor、または default HARNESS_IMPL_BACKEND=cursor の場合、Parallel でも native Worker spawn ではなく task ごとの Cursor companion worktree を使う。

Codex モード（--codex 明示時のみ）

公式プラグイン codex-plugin-cc の companion 経由で Codex CLI にタスクを委託する。

# タスク委託（書き込み可能・worktree 分離）
BASE_REF="$(git rev-parse HEAD)"
WT_ID="codex-$(date +%Y%m%d-%H%M%S)-$"
WORKTREE_PATH=".claude/worktrees/${WT_ID}"
git worktree add -b "codex-work/${WT_ID}" "$WORKTREE_PATH" "$BASE_REF"
HARNESS_CODEX_PRIMARY_ENV_STATE_FILE="$WORKTREE_PATH/.claude/state/codex-primary-environment.json" \
  bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" task --write -C "$WORKTREE_PATH" \
  "タスク内容。完了前にこの worktree で exactly one git commit を作成してください。"

# stdin 経由（大きなプロンプト向け）
CODEX_PROMPT=$(mktemp /tmp/codex-prompt-XXXXXX.md)
# タスク内容を書き出し
cat "$CODEX_PROMPT" | HARNESS_CODEX_PRIMARY_ENV_STATE_FILE="$WORKTREE_PATH/.claude/state/codex-primary-environment.json" \
  bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" task --write -C "$WORKTREE_PATH"
rm -f "$CODEX_PROMPT"

# Lead review 後に承認されたら range を取り込む
git -C "$WORKTREE_PATH" diff "$BASE_REF..HEAD"
WORKTREE_HEAD="$(git -C "$WORKTREE_PATH" rev-parse HEAD)"
git cherry-pick --no-commit "$BASE_REF..$WORKTREE_HEAD"

companion は App Server Protocol 経由で Codex と通信し、 Job 管理・thread resume・構造化出力を提供する。 結果を検証し、品質基準を満たさない場合は自力で修正。

Breezing モード（4 件以上で自動選択 / --breezing で強制）

Lead / Worker / Advisor / Reviewer の役割分離でチーム実行する。 Codex host の Breezing は resolver result に従う。配布 plugin のフラグなし fallback は claude なので、 spawn_agent, wait_agent, send_input, close_agent を使った Codex native subagent orchestration が互換既定。 --backend cursor / --cursor、または user/project config の HARNESS_IMPL_BACKEND=cursor がある時だけ cursor-companion.sh で Cursor worker に委託する。 古い TeamCreate / TaskCreate ベースの説明は採らない。

権限ポリシー:

• 現行の shipped default は bypassPermissions
• --auto-mode は互換な親セッション向けの opt-in rollout フラグとして扱う
• permissions.defaultMode や agent frontmatter の permissionMode には未文書化の autoMode 値を書かない

CC v2.1.69+: nested teammates はプラットフォーム側で禁止されるため、 Worker/Reviewer プロンプトには冗長な nested 防止文言を追加しない。

Lead (this agent)
├── Worker (resolver result: Codex native spawn_agent / codex-companion / cursor-companion) — 実装担当
├── Advisor (claude-code-harness:advisor) — 方針助言
└── Reviewer (code-reviewer agent) — レビュー担当

Phase A: Pre-delegate（準備）:

1. Plans.md を読み込み、対象タスクを特定
2. 依存グラフを解析し、実行順序を決定（Depends カラム）
3. 各タスクの仕様正本 preflight を行い、必要なら docs/spec/00-project-spec.md または既存 spec を実装前に更新
4. 各タスクの effort スコアリング（effort tier 判定 — high/xhigh）
5. node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" で sprint-contract.json を生成
6. bash "${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh" で Reviewer 観点を加え、bash "${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh" で未承認なら停止

Phase B: Delegate（Worker spawn → 必要時 Advisor → レビュー → cherry-pick）:

各タスクについて以下を逐次実行する（依存順）:

API 注記: 以下は Codex native の subagent API 構文で記述する。 backend=claude の時だけ spawn_agent(...), send_input(...), wait_agent(...), close_agent(...) をそのまま使う。 backend=cursor / codex の時は Worker agent を spawn せず、Lead が companion を直接呼ぶ。 Claude Code 向けのサブエージェント構文やメッセージ送信構文は混ぜない。

for task in execution_order:
    # B-0. backend 解決（配布 fallback は claude、user/project default で cursor 可）
    resolver_backend_arg = ""
    if explicit_backend_value in ["claude", "codex", "cursor"]:
        resolver_backend_arg = "--backend {explicit_backend_value}"
    backend = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/resolve-impl-backend.sh\" {resolver_backend_arg}")
    if explicit_flag == "--cursor":
        backend = "cursor"
    if explicit_flag == "--codex":
        backend = "codex"

    # B-1. sprint-contract を生成
    contract_path = bash("node \"${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js\" {task.number}")
    contract_path = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/enrich-sprint-contract.sh\" {contract_path} --check \"DoD を reviewer 観点で確認\" --approve")
    bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/ensure-sprint-contract-ready.sh\" {contract_path}")

    # B-2. Worker 委託（worktree 分離）
    Plans.md: task.status = "cc:WIP"  # 着手時に更新（未着手タスクは cc:TODO のまま）

    if backend == "cursor":
        BASE_REF = git("rev-parse", "HEAD")
        WT_ID = "{task.number}-$(date +%Y%m%d-%H%M%S)-$"
        worktree_path = ".claude/worktrees/cursor-{WT_ID}"
        worktree_branch = "cursor-work/{WT_ID}"
        bash("mkdir -p .claude/worktrees && git worktree add -b {worktree_branch} {worktree_path} {BASE_REF}")
        print("🚀 cursor / $(bash \"${HARNESS_PLUGIN_ROOT}/scripts/model-routing.sh\" --host cursor --role worker --field model) / {branch} / {task.number}")
        companion_prompt = "{task prompt}\n\nAfter making changes, create exactly one git commit in this worktree before returning."
        companion_output = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worktree_path} \"{companion_prompt}\"")
        latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
        if git("-C", worktree_path, "status", "--porcelain") != "":
            git("-C", worktree_path, "add", "-A")
            git("-C", worktree_path, "-c", "user.name=cursor-composer", "-c", "user.email=cursor-composer@local", "commit", "--no-verify", "-m", "cursor: delegated change")
            latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
        if latest_commit == BASE_REF:
            raise EscalationError("cursor companion produced no commit")
        worker_result = {type: "companion-result.v1", baseCommit: BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: worktree_branch, files_changed: git("-C", worktree_path, "diff", "--name-only", "{BASE_REF}..HEAD"), summary: companion_output}
        worker_id = null
    elif backend == "codex":
        BASE_REF = git("rev-parse", "HEAD")
        WT_ID = "{task.number}-$(date +%Y%m%d-%H%M%S)-$"
        worktree_path = ".claude/worktrees/codex-{WT_ID}"
        worktree_branch = "codex-work/{WT_ID}"
        bash("mkdir -p .claude/worktrees && git worktree add -b {worktree_branch} {worktree_path} {BASE_REF}")
        companion_prompt = "{task prompt}\n\nAfter making changes, create exactly one git commit in this worktree before returning."
        companion_state_file = "{worktree_path}/.claude/state/codex-primary-environment.json"
        companion_output = bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worktree_path} \"{companion_prompt}\"")
        latest_commit = git("-C", worktree_path, "rev-parse", "HEAD")
        if latest_commit == BASE_REF:
            raise EscalationError("codex companion produced no commit")
        worker_result = {type: "companion-result.v1", baseCommit: BASE_REF, commit: latest_commit, worktreePath: worktree_path, branch: worktree_branch, files_changed: git("-C", worktree_path, "diff", "--name-only", "{BASE_REF}..HEAD"), summary: companion_output}
        worker_id = null
    else:
        print("🚀 claude / native-subagent / {branch} / {task.number}")
        worker_id = spawn_agent({
            message: "タスク: {task.内容}\nDoD: {task.DoD}\ncontract_path: {contract_path}\nspec_path: {spec_path}\nspec_skip_reason: {spec_skip_reason}\nmode: breezing\n\n作業は分離 worktree で行い、完了後に git commit してください。\n完了時は {commit, worktreePath, branch, files_changed, summary} を返してください。",
            fork_context: true
        })
        worker_result = wait_agent({ targets: [worker_id] })
    # worker_result には {commit, worktreePath, branch, files_changed, summary} が含まれる
    # backend=cursor/codex では Lead が companion stdout を companion-result.v1 に正規化する。

    # B-3. Worker が advice request を返した時だけ、Lead が Advisor を呼ぶ
    if backend == "claude" and worker_result.type == "advisor-request.v1":
        advisor_id = spawn_agent({
            message: worker_result.request_json,
            agent_type: "default",
            fork_context: true
        })
        advisor_result = wait_agent({ targets: [advisor_id] })
        close_agent({ target: advisor_id })
        send_input({
            target: worker_id,
            message: "advisor-response.v1: {advisor_result}"
        })
        worker_result = wait_agent({ targets: [worker_id] })

    # B-4. Lead がレビュー実行（Codex exec 優先）
    if backend == "claude":
        diff_text = git("-C", worker_result.worktreePath, "show", worker_result.commit)
    else:
        diff_text = git("-C", worker_result.worktreePath, "diff", "{worker_result.baseCommit}..HEAD")
    verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
    profile = jq(contract_path, ".review.reviewer_profile")
    review_input = "review-output.json"
    if profile == "runtime":
        review_input = bash("cd {worker_result.worktreePath} && bash \"${HARNESS_PLUGIN_ROOT}/scripts/run-contract-review-checks.sh\" {contract_path}")
        runtime_verdict = jq(review_input, ".verdict")
        if runtime_verdict == "REQUEST_CHANGES":
            verdict = "REQUEST_CHANGES"
        elif runtime_verdict == "DOWNGRADE_TO_STATIC":
            pass  # runtime 検証コマンドなし → static verdict をそのまま使う
    browser_result = ""
    if profile == "browser":
        # browser artifact から route / browser_mode / execution_instructions を再利用して browser runner を起動する。
        browser_artifact = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/generate-browser-review-artifact.sh\" {contract_path}")
        browser_result = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/browser-review-runner.sh\" {browser_artifact}")
        browser_verdict = jq(browser_result, ".browser_verdict")
        if browser_verdict == "REQUEST_CHANGES":
            verdict = "REQUEST_CHANGES"
        elif browser_verdict == "APPROVE" and verdict != "REQUEST_CHANGES":
            verdict = "APPROVE"
        # browser_verdict == PENDING_BROWSER のときは static verdict を維持する
    # review_input が DOWNGRADE_TO_STATIC の場合は static review 結果を使う
    if review_input != "review-output.json" and jq(review_input, ".verdict") == "DOWNGRADE_TO_STATIC":
        review_input = "review-output.json"  # static review の結果にフォールバック
    bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/write-review-result.sh\" {review_input} {latest_commit} --browser-result {browser_result}")

    # B-5. 修正ループ（REQUEST_CHANGES 時、contract の max_iterations まで）
    review_count = 0
    # sprint-contract が存在するときのみ max_iterations を読む。存在しない場合は 3（後方互換）
    MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3
    latest_commit = worker_result.commit
    while verdict == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
        if backend == "claude":
            send_input({
                target: worker_id,
                message: "指摘内容: {issues}\n修正して amend してください"
            })
            # Worker が修正 → amend → 更新された commit hash を返す
            updated_result = wait_agent({ targets: [worker_id] })
            latest_commit = updated_result.commit
        elif backend == "cursor":
            previous_commit = latest_commit
            companion_output = bash("bash \"${HARNESS_PLUGIN_ROOT}/scripts/cursor-companion.sh\" task --write --workspace {worker_result.worktreePath} \"Review findings:\n{issues}\n\nFix the findings and commit the result.\"")
            latest_commit = git("-C", worker_result.worktreePath, "rev-parse", "HEAD")
            if git("-C", worker_result.worktreePath, "status", "--porcelain") != "":
                git("-C", worker_result.worktreePath, "add", "-A")
                git("-C", worker_result.worktreePath, "-c", "user.name=cursor-composer", "-c", "user.email=cursor-composer@local", "commit", "--no-verify", "-m", "cursor: review fix")
                latest_commit = git("-C", worker_result.worktreePath, "rev-parse", "HEAD")
            if latest_commit == previous_commit:
                raise EscalationError("cursor companion retry produced no new commit")
            worker_result.commit = latest_commit
            worker_result.summary = companion_output
        else:
            previous_commit = latest_commit
            companion_state_file = "{worker_result.worktreePath}/.claude/state/codex-primary-environment.json"
            companion_output = bash("HARNESS_CODEX_PRIMARY_ENV_STATE_FILE={companion_state_file} bash \"${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh\" task --write -C {worker_result.worktreePath} \"Review findings:\n{issues}\n\nFix the findings and commit the result.\"")
            latest_commit = git("-C", worker_result.worktreePath, "rev-parse", "HEAD")
            if latest_commit == previous_commit:
                raise EscalationError("codex companion retry produced no new commit")
            worker_result.commit = latest_commit
            worker_result.summary = companion_output
        if backend == "claude":
            diff_text = git("-C", worker_result.worktreePath, "show", latest_commit)
        else:
            diff_text = git("-C", worker_result.worktreePath, "diff", "{worker_result.baseCommit}..HEAD")
        verdict = codex_exec_review(diff_text) or reviewer_agent_review(diff_text)
        review_count++

    # B-6. Worker 終了
    if backend == "claude":
        close_agent({ target: worker_id })

    # B-7. APPROVE → trunk に cherry-pick（feature ブランチ経由）
    # Worker の Branch Guard により trunk HEAD は動かず、commit は feature ブランチ上にある想定
    if verdict == "APPROVE":
        TRUNK=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || echo "main")
        git checkout "$TRUNK"  # safety: 既に trunk なら no-op
        # feature ブランチの commit が既に trunk にある（Branch Guard 失敗時のフォールバック）か確認
        if git("merge-base", "--is-ancestor", latest_commit, "HEAD"):
            pass  # 既に trunk 上 — cherry-pick 不要（再入防止）
        else:
            if backend == "claude":
                git cherry-pick --no-commit {latest_commit}  # feature branch → trunk
            else:
                git cherry-pick --no-commit {worker_result.baseCommit}..{latest_commit}  # companion range → trunk
            git commit -m "{task.内容}"
        # Worker の worktree を remove してから feature ブランチを削除
        if worker_result.worktreePath:
            git worktree remove {worker_result.worktreePath} --force
        if worker_result.branch and worker_result.branch not in ["main", "master"] and worker_result.branch != TRUNK:
            git branch -D {worker_result.branch}
        Plans.md: task.status = "cc:完了 [{hash}]"
        # auto-checkpoint 記録（冪等性ガード (c)）
        # Plans.md 書き換え直後に呼ぶ。失敗しても fail-open（|| true）でループを止めない
        HASH=$(git rev-parse --short HEAD)
        REVIEW_RESULT_PATH=".claude/state/review-results/${task.number}.review-result.json"
        bash "${HARNESS_PLUGIN_ROOT}/scripts/auto-checkpoint.sh" \
            "${task.number}" "${HASH}" "${contract_path}" "${REVIEW_RESULT_PATH}" \
            || true  # fail-open: harness-mem 未起動環境でも継続
    else:
        → ユーザーにエスカレーション

    # B-8. Progress feed
    print("📊 Progress: Task {completed}/{total} 完了 — {task.内容}")

Advisor Protocol（全モード共通）

Advisor は「実装者」でも「レビュー担当」でもない。 迷った時だけ、実行役が次の一歩を決めるための相談役として入る。

1. Worker は generic な subagent を増やさず、必要時だけ advisor-request.v1 を返す
2. Lead が advisor を 1 回だけ呼ぶ
3. Advisor は PLAN / CORRECTION / STOP のどれかを返す
4. Lead はその advice を同じ Worker に返して続行させる
5. Reviewer は最後の成果物だけを見る。advisor の返答に APPROVE / REQUEST_CHANGES を出さない

Solo モードでの Advisor

solo 実行では親セッション自身が Lead を兼ねる。 つまり「自分で実装し、自分で advisor に相談し、最後は独立レビューに回す」形になる。

• 相談条件は loop / breezing と同じ
• 相談 budget も task ごとに最大 3 回で同じ
• STOP はその場で止まり、ユーザー判断へ上げる
• review artifact の gate は飛ばさない

Sprint Contract

sprint-contract は「このタスクを何で合格にするか」を機械でも人でも同じ意味で読める形にする小さな契約ファイルです。 既定の保存先は .claude/state/contracts/<task-id>.sprint-contract.json です。

node "${HARNESS_PLUGIN_ROOT}/scripts/generate-sprint-contract.js" 32.1.1

生成物には次を含めます。

• checks: DoD を分解した確認項目
• non_goals: 今回やらないこと
• runtime_validation: test, lint, typecheck などの検証コマンド
  • If you grep the same symbol twice in the same session, switch to harness_ast_search.
  • For a bugfix where homologous implementations appear across multiple modules, run harness_ast_search to find all implementations before editing.
  • Only when changed files include .ts or .tsx, the DoD requires zero new harness_lsp_diagnostics errors; if the harness MCP is not connected or the changed file types are not eligible, treat diagnostics as not-configured and non-blocking.
• browser_validation: browser reviewer が残すべき UI フロー検証項目
• browser_mode: scripted または exploratory
• route: browser reviewer が playwright / agent-browser / chrome-devtools のどれを使うか
• risk_flags: needs-spike, security-sensitive, ux-regression など
• reviewer_profile: static, runtime, browser

Phase C: Post-delegate（統合・報告）:

1. 全タスクの commit log を集計
2. リッチ完了報告（Completion Report Output Contract と references/completion-report.md の Breezing テンプレート）を出力
3. Plans.md の最終確認（全タスク cc:完了 になっているか）

CI 失敗時の対応

CI が失敗した場合:

1. ログを確認してエラーを特定
2. 修正を実施
3. 同一原因で 3 回失敗したら自動修正ループを停止
4. 失敗ログ・試みた修正・残る論点をまとめてエスカレーション

失敗タスクの自動再チケット化

タスク完了後にテスト/CI が失敗した場合、修正タスク案を自動生成し、承認後に Plans.md へ反映する:

トリガー条件

修正タスクの自動生成

1. 失敗原因を分類（syntax_error / import_error / type_error / assertion_error / timeout / runtime_error）
2. .claude/state/pending-fix-proposals.jsonl に修正タスク案を保存:
   • 番号: 元タスク番号 + .fix サフィックス（例: 26.1.fix）
   • 内容: fix: [元タスク名] - [失敗原因カテゴリ]
   • DoD: テスト/CI が通ること
   • Depends: 元タスク番号
3. ユーザーが approve fix <task_id> を送ると Plans.md に cc:TODO で追加
4. reject fix <task_id> で提案を破棄。pending が1件だけのときは yes / no でも応答可能

レビューループ

実装完了後（ステップ 5 の後）に自動実行される品質検証ステージ。 全モード共通（Solo / Parallel / Breezing）で統一的に適用される。 Parallel モードでは各 Worker が step 10（外部レビュー受付）として同じループを実行する。

レビュー実行の優先順位

1. Codex exec（優先）
   ↓ codex コマンドが存在しない or タイムアウト（120s）
2. 内部 Reviewer agent（フォールバック）

APPROVE / REQUEST_CHANGES の判定基準

レビュアーには以下の閾値基準を渡し、この基準のみで verdict を判定させる。 基準外の改善提案は recommendations として返すが、verdict には影響しない。

重要: minor / recommendation のみの場合は 必ず APPROVE を返すこと。 「あったほうが良い改善」は REQUEST_CHANGES の理由にならない。

Codex exec レビュー（公式プラグイン経由）

タスク開始時の HEAD を BASE_REF として保持し、その ref との差分をレビュー対象にする。 公式プラグイン codex-plugin-cc の companion review を使用する。

# タスク開始時に base ref を記録（Step 2 の cc:WIP 更新前に実行）
BASE_REF=$(git rev-parse HEAD)

# ... 実装完了後 ...

# 公式プラグインの構造化レビューを実行
bash "${HARNESS_PLUGIN_ROOT}/scripts/codex-companion.sh" review --base "${BASE_REF}"
REVIEW_EXIT=$?

verdict マッピング（公式プラグイン → Harness 形式）:

公式プラグインは review-output.schema.json 準拠の構造化出力を返す。 Harness の verdict 形式への変換ルール:

AI Residuals スキャンは引き続き bash "${HARNESS_PLUGIN_ROOT}/scripts/review-ai-residuals.sh" で実行し、 companion review の結果と合わせて最終 verdict を判定する。

# AI Residuals スキャン（companion review と並行実行可能）
AI_RESIDUALS_JSON="$(bash "${HARNESS_PLUGIN_ROOT}/scripts/review-ai-residuals.sh" --base-ref "${BASE_REF}" 2>/dev/null || echo '{"tool":"review-ai-residuals","scan_mode":"diff","base_ref":null,"files_scanned":[],"summary":{"verdict":"APPROVE","major":0,"minor":0,"recommendation":0,"total":0},"observations":[]}')"

内部 Reviewer agent フォールバック

Codex exec が使えない場合（command -v codex が失敗、または exit code ≠ 0）:

Agent tool: subagent_type="reviewer"
prompt: "以下の変更をレビューしてください。判定基準: critical/major → REQUEST_CHANGES、minor/recommendation のみ → APPROVE。diff: {git diff ${BASE_REF}}"

Reviewer agent は Read-only（Write/Edit/Bash 無効）で安全にレビューを実行する。

修正ループ（REQUEST_CHANGES 時）

review_count = 0
# sprint-contract が存在するときのみ max_iterations を読む。存在しない場合は 3（後方互換）
contract_path = get_sprint_contract_path()  # 例: .claude/state/contracts/<task-id>.sprint-contract.json
MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3

while verdict == "REQUEST_CHANGES" and review_count < MAX_REVIEWS:
    1. レビュー指摘を解析（critical / major のみ対象）
    2. 各指摘に対して修正を実装
    3. 再度レビューを実行（同じ判定基準・同じ優先順位）
    review_count++

if review_count >= MAX_REVIEWS and verdict != "APPROVE":
    → ユーザーにエスカレーション
    → 「MAX_REVIEWS 回修正しましたが以下の critical/major 指摘が残っています」+ 指摘一覧を表示
    → ユーザー判断を待つ（続行 / 中断）

Breezing モードでの適用

Breezing モードでは Lead がレビューループを実行する（上記 Phase B 参照）:

1. Worker が worktree 内で実装・commit → Lead に結果返却
2. Lead が Codex exec でレビュー（優先）/ Reviewer agent（フォールバック）
3. REQUEST_CHANGES → Lead が send_input で Worker に修正指示し、wait_agent で再応答を待つ → Worker が amend
4. 修正後、再レビュー（MAX_REVIEWS = read_contract(contract_path, ".review.max_iterations") or 3 回まで）
5. APPROVE → Lead が trunk（デフォルトブランチ）に cherry-pick → Plans.md を cc:完了 [{hash}] に更新

Completion Report Output Contract

Before rendering a Solo, forced single-task Parallel, or Breezing completion report:

1. Resolve the active locale with the shared get_harness_locale function from ${HARNESS_PLUGIN_ROOT}/scripts/config-utils.sh. Pass an explicit session or user language as its optional argument; otherwise keep the resolver priority of project i18n.language, CLAUDE_CODE_HARNESS_LANG, then default en.
2. Unset, invalid, and resolved en render the English template.
3. Only resolved ja renders the Japanese template.
4. Japanese input alone does not select the Japanese template.
5. Read references/completion-report.md and render exactly one template for the selected mode and locale.
6. Keep machine-readable status and review values in English, and never mix English and Japanese labels in one report.

関連スキル

• harness-plan — 実行するタスクを計画する
• harness-sync — 実装と Plans.md を同期する
• harness-review — 実装のレビュー
• harness-release — バージョンバンプ・リリース