[codex] EPIC #62 Harness Engineering を実装

[6uclz1]

概要

EPIC #62（Harness Engineering）の子Issue #56 #57 #58 #59 #60 #61 を、CLIの運用安全性・再現性・契約検証性を中心に一括実装しました。

この変更により、ableton-cli は以下を機械的に保証できるようになります。

• JSON出力の契約違反を実行時に検知して失敗させる
• Abletonなしで Record/Replay による回帰検証を再現する
• --read-only で破壊的コマンドを強制ブロックする
• batch 実行で preflight / retry / assert を宣言的に制御する
• session diff と --compact でエージェント文脈量を削減する
• Skill docs のドリフトを生成+CIゲートで防止する

ユーザー影響（何が改善されるか）

日常利用者・自動化利用者の双方で、失敗が「曖昧に通る」ケースを減らし、失敗時の理由が安定コードで判定可能になります。
特にエージェント運用では、破壊的操作の事故回避、巨大レスポンス圧縮、再現可能テストの導入により、運用の信頼性が上がります。

根本原因

これまでの実装は、機能はあっても次の外骨格が不足していました。

• 出力契約が文書依存で、CIで壊れ方を検知しにくい
• TCP実接続依存のため、Ableton非起動環境で統合回帰が弱い
• read/write境界の強制がなく、運用時の誤実行リスクが残る
• batchの停止条件や再試行条件が宣言できず、運用ごとの差分吸収が難しい
• スキル文書が手編集中心で、CLI実装との差分が発生しやすい

実装内容（要点）

1. 契約検証（#56）

• src/ableton_cli/contracts/ を新設
• runtime.execute_command() 成功時に契約検証を実行
• 代表コマンド（ping, doctor, song info, tracks list, session diff）を対象化
• 契約違反は PROTOCOL_INVALID_RESPONSE + ExitCode 13 で失敗

2. Record/Replay（#57）

• transport を拡張し、RecordingTransport / ReplayTransport を追加
• グローバルオプション --record / --replay を追加
• replay は name + args で照合し、ミスマッチは明示失敗

3. Read-only（#58）

• グローバルオプション --read-only を追加
• dispatch手前で write 系コマンドを拒否
• READ_ONLY_VIOLATION（exit 20）を追加
• batch run/stream でも同じガードを適用

4. Batch拡張（#59）

• batch run/stream の入力仕様を拡張
  • preflight: protocol/hash/required commands の先頭検証
  • retry: 指定エラーコードのみ再試行
  • assert: previous/current 結果の条件検証
• 失敗コードを追加
  • BATCH_PREFLIGHT_FAILED
  • BATCH_ASSERT_FAILED
  • BATCH_RETRY_EXHAUSTED

5. session diff / compact（#61）

• 新規コマンド session diff --from <snapshot.json> --to <snapshot.json> を追加
• グローバルオプション --compact を追加
• JSON出力時に巨大配列を summary+ref へ縮約（決定的出力）

6. docs生成と差分ゲート（#60）

• src/ableton_cli/actions.py を単一ソース化
• tools/generate_skill_docs.py を追加
• 生成対象: skills/ableton-cli/SKILL.md, docs/skills/skill-actions.md
• CIに生成差分ゲートを追加（生成実行 + git diff --exit-code）
• dev_checks に tools/generate_skill_docs.py --check を追加

主な追加/変更ファイル

• src/ableton_cli/contracts/*
• src/ableton_cli/client/transport.py
• src/ableton_cli/client/_client_core.py
• src/ableton_cli/commands/batch.py
• src/ableton_cli/commands/session.py
• src/ableton_cli/session_diff.py
• src/ableton_cli/compact.py
• src/ableton_cli/actions.py
• tools/generate_skill_docs.py
• .github/workflows/ci.yml

検証

ローカルで以下を実行し、すべて通過しています。

• uv run python -m ableton_cli.dev_checks
• uv run ruff check .
• uv run ruff format --check .
• uv run pytest（481 passed）

補足

今回の変更は「フォールバックなし・後方互換維持なし」の方針で実装しています。曖昧な救済経路は追加せず、条件不一致時は明示的に失敗させる設計です。

Closes #56
Closes #57
Closes #58
Closes #59
Closes #60
Closes #61
Closes #62