codex-qa

Codex QA

omo Codex Light エディション（packages/omo-codex/、lazycodex として配布）の QA を行います。 ユーザーの環境には一切手を加えず、実際の Codex で当社のプラグインをテストします。 分離した CODEX_HOME とローカルのモックモデルを使用するため、実際の API 呼び出しは発生せず、実際の ~/.codex が読み書きされることもありません。各ヘルパースクリプトには、稼働中のマシンに対して シナリオを検証する --self-test が用意されているため、スクリプト自体が QA ツールであると同時に 回帰チェックにもなります。

codex-cli 0.140.0（macOS 上の node、jq、tmux、bun）で検証済みです。codex --version で確認してください。 フラグは codex <cmd> --help で確認できます。

基本ルール（実行前にお読みください）

• QA の対象は当社のプラグインのみです。 codex を起動する処理ではすべて、分離した CODEX_HOME（cqa_mk_isolated_home で作成）とローカルのモックモデルプロバイダー （cqa_start_mock）を使用します。実際の ~/.codex に対して QA を行わず、実際のモデル API も呼び出さないでください。 同梱のスクリプトはこれを徹底します。手動で codex を実行する場合は、まず export CODEX_HOME="$(mktemp -d)/codex"; mkdir -p "$CODEX_HOME" を実行してください（設定済みの CODEX_HOME が存在していないと、codex は致命的なエラーになります）。
• 実際のホームディレクトリが変更されていないことを証明してください。 すべてのスクリプトは 実行前後に ~/.codex/config.toml の SHA ハッシュを計算し、変更されていないことを検証します。 手動でスクリプトを作成する場合も同様にしてください。
• 対話型の codex は --profile quotio を挿入するシェル関数です。 Bash スクリプトはこの関数を回避して実際のバイナリを実行するため、対話型のエイリアスには依存しないでください。 references/isolation.md を参照してください。
• フックが実行されたことを証明する、ファーストパーティの方法は app-server の 通知ストリーム（hook/started / hook/completed）です。ログをスクレイピングする方法ではありません。 references/app-server.md を参照してください。
• 取得した JSON / ペインが証拠です — .omo/evidence/<YYYYMMDD>-<slug>/ に保存してください （証拠ファイルがなければ、QA は実施されていません）。このディレクトリは gitignore の対象です。 ファイルはローカルに保持され、PR 本文には概要と決定的な抜粋を記載します。また、このディレクトリ内のものが コミットされることはありません。

セットアップ

cd <this-skill-dir>                        # .agents/skills/codex-qa
bash scripts/lib/common.sh --self-check    # confirm deps + isolation harness

QA の標準環境は Docker です。 最新の codex と設定のコピーを含む使い捨てコンテナ内でこの QA を実行し、 ホストの ~/.codex には触れないようにしてください：script/agent/qa-docker.sh（references/docker-qa.md を参照）。 以下のローカルスクリプトは、Docker を利用できない場合や Windows を使用している場合の代替手段です。

ルーター：ケースを選択

必要なこと…	実行するコマンド	詳細
実際の Codex のターン中にプラグインのフックが実行されることを証明する（ファーストパーティ）	scripts/app-server-drive.sh --plugin	app-server.md
app-server ドライバー自体が動作することを証明する（プラグインなし、高速）	scripts/app-server-drive.sh --self-test	app-server.md
ローカルビルドを分離したホームにインストールし、配置されたことを検証する	scripts/install-verify.sh --self-test	install-verify.md
1 つのコンポーネントのフックロジックを決定論的に検証する（codex なし）	scripts/hook-unit-probe.sh --self-test	components-hooks.md
tmux で実際の TUI をスモークテストする（起動、描画、安定動作）	scripts/tui-smoke.sh --self-test	logging-debug.md
QA 中に実行時ログを確認する	（リファレンスを参照。RUST_LOG / logs DB / /debug-config）	logging-debug.md

スクリプト一覧（各スクリプトは個別の回帰テストです）

スクリプト	--self-test で検証する内容
scripts/lib/common.sh --self-check	依存関係が存在すること、隔離された CODEX_HOME がサンドボックス内に作成され、終了時に自動削除されること、モックモデルが Responses SSE を提供すること、実際の ~/.codex が変更されないこと
scripts/app-server-drive.sh	--self-test：最小構成のターンが完了し、モックアシスタントのテキストが返ること。--plugin：ローカルの omo をインストールしてターンを実行し、sessionStart,userPromptSubmit に対する hook/completed を検証すること
scripts/install-verify.sh	ローカルの omo が隔離されたホームにインストールされること、config.toml で omo@sisyphuslabs が有効になること、コンポーネントのバイナリとエージェントの TOML がサンドボックス内でリンクされること、実際の ~/.codex が変更されないこと
scripts/hook-unit-probe.sh	ultrawork コンポーネントが ulw の UserPromptSubmit で <ultrawork-mode> を注入すること（手動の --component/--event モードにも対応）
scripts/tui-smoke.sh	実際の codex TUI が隔離されたホームで起動し、描画され、終了せずに動作し続けること。ペインをキャプチャすること

開発用 dogfood ビルドと公開済みビルドを実際の ~/.codex（隔離された QA ホームではありません）で見分けるには、リポジトリに含まれる bun run install:codex-dev を使います。このコマンドはプラグインのバージョンを dev として記録します。これは各ターンのフック状態の接頭辞 (OmO dev) と、omo get-local-version の [DEV] バッジで確認できます。手動の dogfood テスト中に、どのビルドが読み込まれているかを確認するために使ってください。実際のホームに書き込むため、上記の隔離された QA フローでは決して実行しないでください。

TUI のビジュアル QA の証跡が必要な場合は、 docs/reference/web-terminal-visual-qa.md に従ってください。実際の xterm.js ウェブターミナルで TUI を描画します。色と CJK の幅が劣化する tmux capture-pane のフレームは決して使わないでください。

node script/qa/web-terminal-visual-qa.mjs --title "Codex TUI QA" \
  --command "codex" --input "{Enter}" \
  --evidence-dir .omo/evidence/<slug>/codex-web-terminal

ヘルパーは実際の pty を実行し、Chrome 上の xterm.js で描画して、 terminal.txt、terminal-ansi.txt、terminal.png（トゥルーカラー）、 metadata.json（--from-file <capture.ansi> は保存済みの生ストリームを再生）を書き出します。 TUI のビジュアル QA にはこの成果物一式を使い、フックの動作を厳密に検証するには app-server-drive.sh --plugin を使ってください。

変更範囲に合わせた QA

• コンポーネント／フックのロジック（packages/omo-codex/plugin/components/*）： 正確な標準出力を確認するために hook-unit-probe.sh を実行し、その後、 実際の接続を検証するために app-server-drive.sh --plugin を実行します。 components-hooks.md を参照してください。
• インストーラー／config.toml（packages/omo-codex/src/install/*）： install-verify.sh を実行します。
• 実行中のセッションに影響するもの（フック、エージェント、MCP の接続）： app-server-drive.sh --plugin を実行し、TUI の経路が重要な場合は tui-smoke.sh --plugin も実行します。

証跡の取得

ev=".omo/evidence/$(date +%Y%m%d)-codex-qa-<slug>"; mkdir -p "$ev"
bash scripts/app-server-drive.sh --plugin > "$ev/app-server-drive.json" 2>&1
bash scripts/install-verify.sh --self-test > "$ev/install-verify.txt" 2>&1

/debugging について

Codex に /debugging コマンドはありません。実行状況を確認するには、アプリサーバーの 通知ストリーム（上記）、アプリサーバーの標準エラー出力での RUST_LOG=debug、 $CODEX_HOME 内の logs SQLite、TUI の /debug-config、および codex debug … サブコマンドを使ってください。 logging-debug.md を参照してください。