Merge pull request #351 from natsuume/fix/opus5-effort-unpin

fix: Opus 5 の effort=medium 固定を撤廃し System Card 準拠のプロンプト指示へ置換

Author: natsuume

.claude-plugin/marketplace.json

@@ -32,7 +32,7 @@
       "name": "pre-push-review",
       "source": "./plugins/pre-push-review",
       "description": "git push 前に 3 つのレビュー (code review / codex review / security review) の完了を強制するプラグイン。レビュー済みマーカーと「commit 列 (HEAD / merge-base の OID) + ブランチ全差分」の同一性検証により、未レビューの commit が remote に到達するのを構造的にブロックする。",
-      "version": "5.2.0",
+      "version": "5.3.0",
       "keywords": ["push", "review", "quality", "codex", "code-review", "security-review", "subagent", "branch-diff", "pr-diff", "parallel"]
     },
     {
@@ -53,7 +53,7 @@
       "name": "agent-discipline",
       "source": "./plugins/agent-discipline",
       "description": "Claude Code の作業規律 (Bash コマンド分解、設計判断の事前確認、issue 駆動の詳細化、排他制御、分業規律など) を SessionStart / SubagentStart hook で注入するプラグイン。auto mode では commit→push→PR→merge の自走方針を配送し、gh issue/pr body の未承認推奨表現も PreToolUse で検知して block する。",
-      "version": "0.22.1",
+      "version": "0.23.0",
       "keywords": ["system-prompt", "discipline", "auto", "issue-driven", "bash", "decompose", "askuserquestion", "permission-mode", "hook", "guardrail", "exclusive-claim", "race-condition", "semantic-validation", "pre-tool-use", "agent-hook"]
     },
     {

README.md

@@ -40,10 +40,10 @@ Claude Code 側で fable-risk-labeler を install していた場合は、plugin
 | [git-guardrails](#git-guardrails) | 0.6.1 | GitHub Flow を構造強制するプラグイン。デフォルトブランチ (master/main) への直接書き込み経路 (commit / push / master/main を head とする PR 作成) を PreToolUse hook で deny し、変更を GitHub 上の PR merge 経由のみに限定する |
 | [enforce-draft-pr](#enforce-draft-pr) | 0.5.0 | `gh pr create` に `--draft` を自動付与する PreToolUse hook プラグイン (任意導入)。PR を常に draft として作成させ、レビューを経て ready 化する運用を支える |
 | [auto-lint-check](#auto-lint-check) | 0.6.0 | 編集後の自動フォーマット適用、git commit 直前の staged ファイル lint、commit 直後の HEAD 再 lint を行うプラグイン。lint の ignore コメント挿入も編集時に禁止する |
-| [pre-push-review](#pre-push-review) | 5.2.0 | `git push` 前に 3 つのレビュー (code review / codex review / security review) の完了を強制するプラグイン。レビュー済みマーカーと「commit 列 (HEAD / merge-base の OID) + ブランチ全差分」の同一性検証により、未レビューの commit が remote に到達するのを構造的にブロックする |
+| [pre-push-review](#pre-push-review) | 5.3.0 | `git push` 前に 3 つのレビュー (code review / codex review / security review) の完了を強制するプラグイン。レビュー済みマーカーと「commit 列 (HEAD / merge-base の OID) + ブランチ全差分」の同一性検証により、未レビューの commit が remote に到達するのを構造的にブロックする |
 | [update-default-branch](#update-default-branch) | 0.4.0 | PR マージ報告を契機にデフォルトブランチを最新化し、追跡先が消えたローカルブランチを片付けるプラグイン |
 | [natsuume-statusline](#natsuume-statusline) | 0.10.0 | Claude Code の statusLine 表示 (パス / repo / branch / 変更量 / context 使用量 / レートリミット) を提供するプラグイン。`/natsuume-statusline:setup` で `~/.claude/settings.json` に登録する |
-| [agent-discipline](#agent-discipline) | 0.22.1 | 作業規律を SessionStart / SubagentStart prompt で配送し、gh issue/pr body の未決定事項を PreToolUse で検知するプラグイン |
+| [agent-discipline](#agent-discipline) | 0.23.0 | 作業規律を SessionStart / SubagentStart prompt で配送し、gh issue/pr body の未決定事項を PreToolUse で検知するプラグイン |
 | [ui-discipline](#ui-discipline) | 0.4.1 | UI 実装の 10 規律を SessionStart / SubagentStart prompt で常時注入するプラグイン。具体例は ui-patterns Skill が提供する |
 | [natsuume-writing](#natsuume-writing) | 0.6.1 | natsuume の文体規則でテックブログ・技術書の執筆を支援するプラグイン |
 | [codex-advisor](#codex-advisor) | 2.0.1 | Codex rescue / review / advisor を role 固有 foreground subagent に閉じ込め、追跡喪失から復旧する。pre-pushを含むCodex review 5サイクルごとの根本方針 advisor checkpointも強制する (要 openai-codex plugin + Codex CLI) |

plugins/agent-discipline/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-discipline",
-  "version": "0.22.1",
+  "version": "0.23.0",
   "author": {"name": "natsuume", "url": "https://github.com/natsuume"},
   "description": "Claude Code の作業規律 (Bash コマンド分解、設計判断の事前確認、issue 駆動の詳細化、排他制御、分業規律など) を SessionStart / SubagentStart hook で注入するプラグイン。auto mode では commit→push→PR→merge の自走方針を配送し、gh issue/pr body の未承認推奨表現も PreToolUse で検知して block する。"
 }

plugins/agent-discipline/README.md

@@ -4,10 +4,19 @@ Claude Code の振る舞い規律 (= agent としての discipline) を配送す
 
 ## バージョン
 
-v0.22.1
+v0.23.0
 
 (注: v0.7.4 〜 v0.11.0 の変更点節は本 README に未追記の既存 drift。各バージョンの変更内容はリポジトリ README の plugin 一覧テーブルおよび各 PR を参照)
 
+### v0.22.1 → v0.23.0 の変更点
+
+Claude Opus 5 System Card の実測に基づき、分業規律の Opus 5 effort=medium 固定を撤廃してプロンプト指示へ置換した。
+
+- `discipline-fable.md` / `discipline-sonnet.md` / `discipline-opus.md` の `rule:delegation-rules` から「Opus 5 を使う委任では effort を medium にする」(v0.20.0 導入の fail-closed 文面) を削除し、「effort を固定しない: 難度・コストに応じて選択してよい (機械的・コスト優先の作業は低め、長期・多段の推論が品質を左右する作業は高め。性能は effort に対して単調増加とは限らない)」の非拘束の目安へ置換した。「Sonnet 系には effort を指定しない」の末尾も「effort を明示する場合は Opus 5 への委任に限る」へ整合させた
+- `rule:delegation-instruction` の「汎用的な再確認指示を加えない」段落の直前に「Opus 5 への委任指示にはスコープ制限の 1 文を必ず含める」段落を追加した。System Card §8.4 (FrontierCode) は high 超の effort でのタスク範囲外変更によるスコア低下と、スコープ制限指示 1 文での回復 (モデル限界ではない) を報告しており、effort の固定ではなくプロンプト指示で副作用を抑える
+- 根拠: System Card §8.5 (FrontierBench) / §8.10.1 (HLE) / §8.12.2 (BenchCAD) は高難度タスクの effort スケーリングを、§6.2.1 (pilot feedback) は高 effort での自己修正ループを報告している。自己修正ループ対策は既存の「Opus 5 への委任では汎用的な再確認指示を加えない」を維持する
+- 契約テスト `tests/test_opus5_effort_unpin.py` を追加し、旧固定文 6 断片の不在・新指針とスコープ制限指示の存在 (節スコープ + 段落隣接)・「Sonnet 系には effort を指定しない」の保全を固定した
+
 ### v0.22.0 → v0.22.1 の変更点
 
 - `discipline-fable.md` / `discipline-sonnet.md` / `discipline-opus.md` 間の drift を修復した (同一メッセージでの並列委任の明記、調査・レビュー・検証系への対象拡張、fork 例外の代替手段の明記、WebSearch 等の特定ツール使用例の補完、目的・背景を渡す意図の明記、state を書くテストでの隔離 TMPDIR 例の補完、`discipline-fable.md` / `discipline-sonnet.md` の xhigh ハードコード記述の除去)

plugins/agent-discipline/hooks/prompts/discipline-fable.md

@@ -30,10 +30,10 @@ Fable (メインセッション) が担う作業:
 ## 2. 委任時の規律
 
 - モデルは Sonnet 系または Opus を使う (機械的で並列化可能な作業に限り Haiku も可)。**Fable をサブエージェントに使わない** (明示指定もしない、model 未指定での継承もさせない)
-- **Opus 5 を使う委任では effort を medium にする** (難度による引き上げ・引き下げをしない)。Workflow の `agent()` では `effort: 'medium'` を明示する。設定の優先順位を解決した実効 effort が medium になると保証できない場合 (effort を指定できない Agent ツール起動で agent 定義にも effort が無い等) は Opus 5 を使わず実効 model を Sonnet 系にし、上位設定の強制でそれも保証できなければ委任せず設定競合をユーザに報告する
+- **Opus 5 を使う委任では effort を固定しない**: 難度・コストに応じて選択してよい。境界が明確な機械的・コスト優先の作業では低め、長期・多段の推論が品質を左右する検証・調査・実装では高めを検討する (性能は effort に対して単調増加とは限らない)。高 effort の副作用はセクション 3 の Opus 5 固有指示 (スコープ制限・汎用再確認指示の禁止) で抑え、明示しない経路ではセッション既定の継承でよい
 - Agent ツール / Workflow script の `agent()` では **model を常に明示する**。model 未指定はメインセッション (= Fable) の継承が既定のため (ツール側の「未指定 = 継承」推奨に対する、Fable セッション限定の意図的な例外)
 - この環境で `CLAUDE_CODE_SUBAGENT_MODEL` が設定されている場合、その値は model の明示指定や agent 定義の frontmatter より優先され、全サブエージェント (Workflow 内部の `agent()` 含む) がその値で実行される。env が `sonnet` の間は opus を指定しても sonnet で走るため、品質・コストの見積りはその前提で行う
-- **Sonnet 系には effort を指定しない**: セッション既定の effort の継承を前提とし、Workflow の `agent()` でも effort オプションは付けない。effort を明示するのは Opus 5 の medium 指定のみ
+- **Sonnet 系には effort を指定しない**: セッション既定の effort の継承を前提とし、Workflow の `agent()` でも effort オプションは付けない。effort を明示する場合は Opus 5 への委任に限る
 - **独立した subtask は同一メッセージで並列に委任し、完了をブロックして待たずに他の作業を進める**。介入するのは、エスカレーション (セクション 4) を受けたとき、または明らかな逸脱・コンテキスト不足の兆候があるときに限る
 - 前段の文脈・成果物に依存する後続 subtask は、新規起動ではなく **SendMessage で同一エージェントを継続** し、コンテキストと cache を再利用する (Workflow の `agent()` は対象外)。継続時も各指示はセクション 3 の必須要素を毎回満たす
 - **fork subagent は原則使用しない**: 全会話コンテキストを継承するため Fable セッションでは入力コストが大きく、model 指定も無視される。代わりに、必要な文脈を指示文に埋め込んだ新規起動 (セクション 2 の self-contained 要件) を使う。コンテキスト継承が不可欠な委任に限り fork を例外として許容する
@@ -50,6 +50,8 @@ Fable (メインセッション) が担う作業:
 4. **default-deny 安全弁 (必須の定型文)**: 「この指示に明記されていない副作用を伴う操作 (ファイル変更・git 状態変更・外部サービス呼び出し等) が必要になった場合、実行せずエスカレーション (セクション 4) して終了すること」という趣旨の一文を必ず入れる。事前列挙の網羅性に依存しない安全弁である
 5. **終了時自己点検**: 副作用を許可した委任では、終了時に対象 (実リポジトリ等) の状態確認と差分報告を受入条件に含める
 
+**Opus 5 への委任指示にはスコープ制限の 1 文を必ず含める**: 高 effort の Opus 5 には依頼範囲を超えた変更 (依頼外のリファクタリング・改善等) に踏み込む傾向が実測されており、「依頼されたタスクのスコープ内に留まり、範囲外の変更を行わない」旨の簡潔な指示でほぼ抑止できる (モデル固有の限界ではなくプロンプトで回復可能)。1. の禁止 (スコープ付き) と併せて毎回明記する。
+
 **Opus 5 への委任では汎用的な再確認指示を加えない**: 「double-check your answer」「回答前に再検証せよ」のような一般的な再確認指示は、指示なしで自己検証する Opus 5 に過剰検証 (トークン浪費) を招くため書かない。タスク固有の受入条件の検証指示と 5. の終了時自己点検 (副作用の状態報告) はこの対象外であり維持する。
 
 <!-- rule:escalation -->

plugins/agent-discipline/hooks/prompts/discipline-opus.md

@@ -56,9 +56,9 @@ Opus 5 は指示がなくても自分の作業を検証・修正する。この
 
 - **委任は真に独立した相応の規模の作業に限る**: 数回の tool call で終わる作業・逐次依存が強く並列化できない作業は委任せず直接行う。1 体で完了できる作業に複数体を使わず、spawn 数を低く保つ
 - **Fable をサブエージェントに使わない**: model に fable 系を明示指定しない (PreToolUse hook (block-fable-subagent.sh) が deny する)。非 Fable セッションでは model 未指定の継承先も非 Fable なので、未指定 (継承) を既定としてよい
-- **Opus 5 を使う委任では effort を medium にする** (難度による引き上げ・引き下げをしない)。Workflow の `agent()` では `effort: 'medium'` を明示する。設定の優先順位を解決した実効 effort が medium になると保証できない場合 (effort を指定できない Agent ツール起動で agent 定義にも effort が無い等) は Opus 5 を使わず実効 model を Sonnet 系にし、上位設定の強制でそれも保証できなければ委任せず設定競合をユーザに報告する
+- **Opus 5 を使う委任では effort を固定しない**: 難度・コストに応じて選択してよい。境界が明確な機械的・コスト優先の作業では低め、長期・多段の推論が品質を左右する検証・調査・実装では高めを検討する (性能は effort に対して単調増加とは限らない)。高 effort の副作用はセクション 3 の Opus 5 固有指示 (スコープ制限・汎用再確認指示の禁止) で抑え、明示しない経路ではセッション既定の継承でよい
 - **`CLAUDE_CODE_SUBAGENT_MODEL` が設定されている場合**、その値は model の明示指定や agent 定義の frontmatter より優先され、全サブエージェント (Workflow 内部の `agent()` 含む) がその値で実行される。品質・コストは env の実効モデルで走る前提で見積もる (メインセッションと同一モデルとは限らない)
-- **Sonnet 系には effort を指定しない**: effort を指定できない委任経路ではセッション既定の effort を継承する。このセッションの既定が medium の場合は Sonnet 系サブエージェントも medium で走る前提で品質・コストを見積もる (effort を明示するのは Opus 5 の medium 指定のみ)
+- **Sonnet 系には effort を指定しない**: effort を指定できない委任経路ではセッション既定の effort を継承する。このセッションの既定が medium の場合は Sonnet 系サブエージェントも medium で走る前提で品質・コストを見積もる (effort を明示する場合は Opus 5 への委任に限る)
 - **独立した subtask は同一メッセージで並列に委任し、完了をブロックして待たずに他の作業を進める**。介入するのは、エスカレーション (セクション 4) を受けたとき、または明らかな逸脱・コンテキスト不足の兆候があるときに限る
 - 前段の文脈・成果物に依存する後続 subtask は、新規起動ではなく **SendMessage で同一エージェントを継続** し、コンテキストと cache を再利用する (Workflow の `agent()` は対象外)。継続時も各指示はセクション 3 の必須要素を毎回満たす
 - **fork subagent は原則使用しない**: 全会話コンテキストを継承するため入力コストが大きい。代わりに、必要な文脈を指示文に埋め込んだ新規起動 (セクション 2 の self-contained 要件) を使う。コンテキスト継承が不可欠な委任に限り fork を例外として許容する
@@ -81,6 +81,8 @@ Opus 5 は指示がなくても自分の作業を検証・修正する。この
 4. **default-deny 安全弁 (必須の定型文)**: 「この指示に明記されていない副作用を伴う操作 (ファイル変更・git 状態変更・外部サービス呼び出し等) が必要になった場合、実行せずエスカレーション (セクション 4) して終了すること」という趣旨の一文を必ず入れる。事前列挙の網羅性に依存しない安全弁である
 5. **終了時自己点検**: 副作用を許可した委任では、終了時に対象 (実リポジトリ等) の状態確認と差分報告を受入条件に含める (例: `git status --short` の実出力を報告に添付し、変更が指示の列挙ファイルに限定されていることを確認させる)
 
+**Opus 5 への委任指示にはスコープ制限の 1 文を必ず含める**: 高 effort の Opus 5 には依頼範囲を超えた変更 (依頼外のリファクタリング・改善等) に踏み込む傾向が実測されており、「依頼されたタスクのスコープ内に留まり、範囲外の変更を行わない」旨の簡潔な指示でほぼ抑止できる (モデル固有の限界ではなくプロンプトで回復可能)。1. の禁止 (スコープ付き) と併せて毎回明記する。
+
 **Opus 5 への委任では汎用的な再確認指示を加えない**: 「double-check your answer」「回答前に再検証せよ」のような一般的な再確認指示は、指示なしで自己検証する Opus 5 に過剰検証 (トークン浪費) を招くため書かない。タスク固有の受入条件の検証指示と 5. の終了時自己点検 (副作用の状態報告) はこの対象外であり維持する。
 
 **例**: