kanban-codex-lane

Kanban Codex Lane

概要

このスキルでは、Kanban ワーカー向けの軽量な Hermes+Codex デュアルレーン規約を定めます。タスクのオーナーは常に Hermes です。Hermes は kanban_show を呼び出し、Codex が適切かどうかを判断し、分離されたワークスペースを作成または選択して、Codex を起動・監視し、差分を調整して、検証を実施したうえで、最終的な kanban_complete または kanban_block の引き継ぎを書きます。Codex は入力レーンにすぎません。Codex の出力はタスク完了の合図ではなく、信頼できるレビュアーでもありません。また、永続的な Kanban の状態を直接書き込むこともできません。

この規約は、ディスパッチャーを変更せずに、Hermes ワーカーが範囲を限定した実装支援に Codex を利用できるようにするものです。ディスパッチャーは引き続き Hermes ワーカーを起動する必要があります。ワーカーは、必要に応じて自身の実行中に Codex を起動し、独立したレビューとテストの後で、そのレーンの成果をすべて受け入れる、一部受け入れる、または却下できます。

使用する場合

次の条件をすべて満たす場合は、Codex レーンを使用します。

• Kanban タスクがコーディング、リファクタリング、ドキュメント作成、テスト、または機械的な移行に関するもので、受け入れ条件が明確であること。
• 範囲を限定した差分を Hermes が1回の実行で評価できること。
• リポジトリを、分離された git worktree／ブランチにコピーまたはチェックアウトできること。
• Codex の終了後に、Hermes 自身が関連するテストを実行できること。
• すべての安全上の制約と、変更してはならないファイルをプロンプトで指定できること。

次の条件のいずれかに当てはまる場合は、Codex レーンを使用しないでください。

• Kanban の本文にまだ記載されていない人間の判断がタスクに必要であること。
• ワーカーがリポジトリにアクセスできない、Codex の認証情報がない、または結果を調整する時間がないこと。
• 変更がシークレット、認証情報ストア、個人ユーザーデータ、または本番の注文入力システムに関わること。
• 別のエージェントを起動するより、簡単な直接編集のほうが速く、安全であること。
• タスクが調査のみであり、差分ではなく文書化された引き継ぎを作成すべきであること。
• Codex の自己申告だけを根拠に、ワーカーが Done にしようとするおそれがあること。

オーナーシップのルール

1. Kanban のライフサイクルは Hermes が管理します。Codex は、ワーカーの代わりとして kanban_complete、kanban_block、kanban_create、ゲートウェイメッセージ送信、またはいずれかの Hermes ボード CLI を決して呼び出してはなりません。
2. 最終的な受け入れ判断は Hermes が行います。Codex のコミットや差分は、レビューと検証が終わるまで、信頼できないパッチとして扱います。
3. テストの実行は Hermes が担当します。Codex がテストを実行することはできますが、その結果は参考情報にすぎません。必要な検証は、リポジトリの正式なラッパーを使って Hermes が再実行します。
4. 安全性は Hermes が管理します。Codex が安全上の境界、リスクゲート、実取引の動作、またはシークレットの取り扱いを変更した場合、テストに合格していてもそのレーンを却下します。
5. クリーンアップは Hermes が担当します。応答しなくなった Codex プロセスを終了し、不要になった一時 worktree を削除します。

必須の worktree とブランチのパターン

汚れた共有チェックアウトで Codex を直接実行してはなりません。Kanban タスクに関連付けられ、信頼できない編集を分離できるブランチ名／worktree 名を使います。

推奨変数：

TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
REPO="/path/to/repo"
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"

分離されたレーンを作成します。

git -C "$REPO" fetch --all --prune
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
git -C "$WORKTREE" status --short --branch

現在の Kanban ワークスペースがこのタスク用に作成された分離 git worktree である場合、git status --short が、意図的な Hermes の編集を除いてクリーンであることを条件として、その中に Codex 用の兄弟ブランチを作成できます。それ以外の場合は、別の一時 worktree を作成し、調整後に受け入れたコミットを cherry-pick またはコピーして戻します。

調整後のクリーンアップ：

git -C "$REPO" worktree remove "$WORKTREE"
git -C "$REPO" branch -D "$BRANCH"  # only after accepted commits were copied/cherry-picked or intentionally rejected

レビュー用の成果物として必要な場合は、worktree を残します。その場合は codex_lane.artifacts に記録し、引き継ぎにも記載します。

Codex の利用可否チェック

Codex を起動する前に、これらの確認を実行します。Codex を利用できない場合は、レーンをスキップする通常の理由になります。Hermes がタスクを直接実行できるなら、タスクのブロッカーにはなりません。

command -v codex
codex --version
codex features list | grep -i goals || true

/goal のサポートが必要な場合は、利用可能であることを確認してから、機能フラグを有効にするか、それを使って起動します。

codex features enable goals || true
codex --enable goals --version

認証には OPENAI_API_KEY または Codex CLI の OAuth 状態（多くの場合 ~/.codex/auth.json）を使用できます。トークンファイルを表示してはなりません。OPENAI_API_KEY がないことは、認証を利用できない証拠にはなりません。

モードの選択

範囲が明確な単発の編集で、Codex に自動で終了させる場合は codex exec を使用します。

terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)

永続的な目標の追跡が有用な、より広範な複数ステップの作業に限り、Codex の /goal を使用します。PTY／tmux セッションで対話的に起動するか、デフォルトで無効になっている場合は codex --enable goals を使用します。目標の内容だけで完結するように、リポジトリのパス、タスク ID、安全上の制約、許可された範囲、受け入れ基準、テスト、コミットに関する要件を含めてください。

Codex に貼り付ける /goal の目標文の例：

/goal Work in this repository only: <WORKTREE>. Task: <TASK_ID> <TITLE>.
Hermes owns the Kanban lifecycle; do not call Hermes kanban tools or messaging.
Create small commits on branch <BRANCH>. Follow the PMB safety constraints in the prompt.
Run the requested verification commands and report exact outputs. Stop after producing a diff and summary.

prediction-market-bot や安全性が重要なリポジトリでは、--yolo を使用しないでください。分離されたワークツリー内では --full-auto を優先し、その後 Hermes の調整を行ってください。

プロンプトの作成

prediction-market-bot の作業には、リンク先のテンプレート templates/pmb-codex-lane-prompt.md を使用します。他のリポジトリでは、同じ構成を維持し、PMB 固有の安全ブロックをリポジトリ固有の不変条件に置き換えてください。

すべての Codex プロンプトには、以下を含める必要があります。

• task_id、タイトル、Kanban の受け入れ基準の全文。
• リポジトリのパス、ワークツリーのパス、ブランチ名、許可されたファイルの範囲。
• 明示的な記述：Kanban のライフサイクルを管理するのは Hermes であり、Codex は入力レーンのみを担当します。
• 必須の出力：簡潔な要約、変更したファイル、コミット、実行したテスト、既知のリスク。
• 禁止事項：シークレットへのアクセス、外部へのメッセージ送信、ボードの変更、無関係なリファクタリング、必要な場合を除く依存関係のアップグレード。
• Codex が実行してよい検証コマンドと、その後 Hermes が実行するコマンド。

PMB の場合は、以下の必須安全制約をそのまま含めてください。

PMB safety constraints:
- live-SIM is paper-only; do not add or enable live REST order entry.
- Never use market orders.
- Do not add execution crossing or bypass price/risk checks.
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
- Keep research/selection outside the C++ hot path unless explicitly requested.
- Do not read, print, write, or require secrets/tokens/credentials.

監視、タイムアウト、停止時の動作

長時間実行する Codex レーンは、PTY と完了通知を使用してバックグラウンドで開始します。

result = terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)
session_id = result["session_id"]

作業に干渉せずに監視します。

process(action="poll", session_id=session_id)
process(action="log", session_id=session_id, limit=200)
process(action="wait", session_id=session_id, timeout=300)

停止条件：

• タスクに残された実行時間の間、有用な出力がない。
• Codex がシークレット、本番環境の認証情報、外部への権限を要求する。
• Codex がワークツリー外のファイルを変更しようとする。
• Codex が無関係な書き換えや依存関係の大幅な変更を始める。
• ワーカーのタイムアウトが近づいても Codex の実行が続いており、安全に利用できる部分成果物がない。

停止コマンド：

process(action="kill", session_id=session_id)

停止後、git status --short を確認し、安全な場合に限り有用なパッチを保存して、具体的な rejected_reason とともに codex_lane.result: timed_out または rejected を記録します。

調整チェックリスト

Codex レーンの結果を受け入れる前に、Hermes は以下のチェックリストを実施する必要があります。

• git -C <WORKTREE> status --short --branch の結果に、想定したファイルのみが表示される。
• Hermes が git -C <WORKTREE> diff --stat と git diff を確認した。
• シークレット、認証情報、生成されたキャッシュ、無関係なデータ、ローカルの成果物が含まれていない。
• PMB の安全制約が維持されている：ライブ REST 注文の送信なし、成行注文なし、約定を横切る執行なし、見せかけの受動約定／損益なし、リスクゲートの緩和なし、シークレットなし。
• Codex のコミットが、クリーンに cherry-pick または squash できる程度に小さい。
• Hermes が、Hermes Agent には scripts/run_tests.sh を使用し、他のリポジトリにはそのリポジトリで文書化されたラッパーを使用して、正規のテストを自ら実行した。
• Codex が実行したテストは、Hermes が実行したテストと分けて記載されている。
• 受け入れたコミット／差分が、Hermes が管理するワークスペース／ブランチに適用された。
• 却下した作業または部分的な作業には、具体的な理由と、参考になる場合は成果物のパスが記載されている。

受け入れ結果：

• accepted：Codex の差分／コミットを確認し、適用して検証した。
• partial：編集または cherry-pick 後に Codex の作業の一部を受け入れ、却下した部分を記録した。
• rejected：Codex の変更を一切受け入れず、その理由を記録した。
• timed_out：Codex がレーンの実行時間を超過した。有用な成果物が存在する場合と、存在しない場合がある。

kanban_complete メタデータスキーマ

レーンを検討したすべてのタスクで、このオブジェクトを metadata.codex_lane の下に含めてください。Codex を使用しなかった場合は、used: false を設定し、rejected_reason または同階層の notes フィールドで理由を説明してください。

{
  "codex_lane": {
    "used": true,
    "mode": "exec | goal | skipped",
    "worktree": "/absolute/path/to/codex/worktree",
    "branch": "codex/t_caa69668/20260508100000",
    "command": "codex exec --full-auto ...",
    "result": "accepted | rejected | partial | timed_out",
    "accepted_commits": ["<sha1>", "<sha2>"],
    "rejected_reason": "empty when fully accepted; otherwise concrete reason",
    "tests_run": [
      {"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
      {"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
    ],
    "artifacts": ["/absolute/path/to/log-or-patch"]
  }
}

意図的に Codex を使用しないタスクの場合：

{
  "codex_lane": {
    "used": false,
    "mode": "skipped",
    "worktree": null,
    "branch": null,
    "command": null,
    "result": "rejected",
    "accepted_commits": [],
    "rejected_reason": "Direct Hermes edit was smaller and safer than spawning Codex.",
    "tests_run": [],
    "artifacts": []
  }
}

よくある落とし穴

1. Codex の自己申告を検証済みとみなす。必ず差分を確認し、Hermes からテストを再実行してください。
2. ユーザーの変更が残っているメインのチェックアウトで Codex を実行する。必ずワークツリー／ブランチで分離してください。
3. Kanban の管理を Codex に任せる。Codex は進捗を要約できますが、ボードの状態を更新するのは Hermes です。
4. プロンプトに PMB の安全性に関する不変条件を記載し忘れる。安全性に関する文言が欠けている場合は、レーンの設定に失敗しています。
5. 簡単な編集に /goal を使用する。複数ステップの作業を継続的に進める必要がない限り、codex exec を優先してください。
6. 理由を記録せずに、停止したレーンを終了する。rejected_reason でその判断の理由を説明する必要があります。
7. テストに合格したという理由で、範囲外の広範なクリーンアップを受け入れる。範囲外の変更は却下するか、対象範囲内の変更のみをチェリーピックしてください。

検証チェックリスト

• Codex はスキップされたか、command -v codex、codex --version、および任意のゴール機能チェックの実行後にのみ開始された。
• Codex は分離されたワークツリー／ブランチでのみ実行された。
• プロンプトにタスクの範囲、所有権のルール、該当する場合は PMB の安全性に関する制約、および検証コマンドが含まれていた。
• Hermes が git diff と安全性に関わるファイルを確認した。
• Hermes が正式なテストを独立して実行した。
• kanban_complete.metadata.codex_lane が上記のスキーマに従っている。
• 一時プロセスと不要なワークツリーがクリーンアップされた。