claude-dev-env 2.10.0 → 2.12.0

package/_shared/advisor/scripts/tests/test_model_tier_run_validator.py

@@ -33,6 +33,8 @@ main = model_tier_run_validator.main
 load_model_tier_run_from_json_path = (
     model_tier_run_validator.load_model_tier_run_from_json_path
 )
+ADVISOR_MODEL_TIER = model_tier_run_validator.ADVISOR_MODEL_TIER
+CODEX_BIND_SUCCESS_TOKEN = model_tier_run_validator.CODEX_BIND_SUCCESS_TOKEN
 
 
 def test_clean_single_spawn_at_top_of_slice_passes() -> None:
@@ -45,6 +47,66 @@ def test_clean_single_spawn_at_top_of_slice_passes() -> None:
     assert validate_model_tier_run(run) is None
 
 
+def test_sol_codex_bind_is_first_success_when_enabled() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER, "Fable", "Opus"],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": CODEX_BIND_SUCCESS_TOKEN}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        is_sol_enabled=True,
+    )
+    assert validate_model_tier_run(run) is None
+
+
+def test_sol_failure_falls_through_to_fable_when_enabled() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER, "Fable", "Opus"],
+        attempts=[
+            {"tier": ADVISOR_MODEL_TIER, "result": "unavailable"},
+            {"tier": "Fable", "result": "spawned"},
+        ],
+        selected_tier="Fable",
+        is_sol_enabled=True,
+    )
+    assert validate_model_tier_run(run) is None
+
+
+def test_sol_rung_precedes_third_party_cli_floor_when_enabled() -> None:
+    run = ModelTierRun(
+        own_tier="ThirdParty",
+        candidate_tiers=[ADVISOR_MODEL_TIER, "Fable", "Opus"],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": CODEX_BIND_SUCCESS_TOKEN}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        is_sol_enabled=True,
+    )
+
+    assert validate_model_tier_run(run) is None
+
+
+def test_sol_codex_result_requires_sol_candidate() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=["Fable", "Opus"],
+        attempts=[{"tier": "Fable", "result": CODEX_BIND_SUCCESS_TOKEN}],
+        selected_tier="Fable",
+    )
+    with pytest.raises(ModelTierRunError):
+        validate_model_tier_run(run)
+
+
+def test_sol_spawned_result_does_not_count_as_codex_success() -> None:
+    run = ModelTierRun(
+        own_tier="Opus",
+        candidate_tiers=[ADVISOR_MODEL_TIER, "Fable", "Opus"],
+        attempts=[{"tier": ADVISOR_MODEL_TIER, "result": "spawned"}],
+        selected_tier=ADVISOR_MODEL_TIER,
+        is_sol_enabled=True,
+    )
+    with pytest.raises(ModelTierRunError):
+        validate_model_tier_run(run)
+
+
 def test_fallthrough_to_floor_tier_passes() -> None:
     run = ModelTierRun(
         own_tier="Opus",
@@ -223,6 +285,23 @@ def test_cli_validates_json_log_file(tmp_path: Path) -> None:
     assert loaded_run.selected_tier == "Fable"
 
 
+def test_cli_rejects_non_boolean_sol_enabled(tmp_path: Path) -> None:
+    log_path = tmp_path / "invalid-sol-enabled.json"
+    log_path.write_text(
+        json.dumps(
+            {
+                "own_tier": "Opus",
+                "candidate_tiers": ["Fable", "Opus"],
+                "attempts": [{"tier": "Fable", "result": "spawned"}],
+                "selected_tier": "Fable",
+                "sol_enabled": "false",
+            }
+        ),
+        encoding="utf-8",
+    )
+    assert main([str(log_path)]) == 2
+
+
 def test_cli_rejects_incomplete_fallback_log(tmp_path: Path) -> None:
     log_path = tmp_path / "incomplete-walk.json"
     log_path.write_text(

package/_shared/advisor/scripts/tests/test_tier_model_ids.py

@@ -10,6 +10,26 @@ from types import ModuleType
 import pytest
 
 
+constants_root = Path(__file__).parent.parent / "config"
+if str(constants_root) not in sys.path:
+    sys.path.insert(0, str(constants_root))
+
+from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
+    ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS,
+    ALL_CLI_MODEL_ID_BY_TIER,
+    ALL_KNOWN_TIER_NAMES,
+    ALL_MODEL_TIERS,
+    HOST_PROFILE_CLAUDE,
+    HOST_PROFILE_THIRD_PARTY,
+    THIRD_PARTY_MODEL_TIER,
+)
+from advisor_scripts_constants.advisor_route_constants import (  # noqa: E402
+    ADVISOR_CODEX_MODEL_ID,
+    ADVISOR_MODEL_TIER,
+    ALL_CODEX_MODEL_ID_BY_TIER,
+)
+
+
 def _load_tier_model_ids_module() -> ModuleType:
     scripts_root = Path(__file__).parent.parent
     module_path = scripts_root / "tier_model_ids.py"
@@ -26,21 +46,9 @@ def _load_tier_model_ids_module() -> ModuleType:
 
 tier_model_ids = _load_tier_model_ids_module()
 resolve_cli_model_id = tier_model_ids.resolve_cli_model_id
+resolve_codex_model_id = tier_model_ids.resolve_codex_model_id
 canonical_tier_name = tier_model_ids.canonical_tier_name
 detect_host_profile = tier_model_ids.detect_host_profile
-constants_root = Path(__file__).parent.parent / "config"
-if str(constants_root) not in sys.path:
-    sys.path.insert(0, str(constants_root))
-
-from advisor_scripts_constants.model_tier_run_validator_constants import (  # noqa: E402
-    ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS,
-    ALL_CLI_MODEL_ID_BY_TIER,
-    ALL_KNOWN_TIER_NAMES,
-    ALL_MODEL_TIERS,
-    HOST_PROFILE_CLAUDE,
-    HOST_PROFILE_THIRD_PARTY,
-    THIRD_PARTY_MODEL_TIER,
-)
 
 SCRIPTS_ROOT = Path(__file__).parent.parent
 DOCUMENTED_RESOLVE_ONE_LINER = (
@@ -94,14 +102,28 @@ def test_sendmessage_reply_wait_is_positive_bound() -> None:
     assert ADVISOR_SENDMESSAGE_REPLY_WAIT_SECONDS == 120
 
 
+def test_resolve_codex_model_id_maps_sol() -> None:
+    assert resolve_codex_model_id(f" {ADVISOR_MODEL_TIER.lower()} ") == (
+        ADVISOR_CODEX_MODEL_ID
+    )
+
+
+def test_resolve_codex_model_id_rejects_claude_tier() -> None:
+    with pytest.raises(ValueError, match="not a known model tier"):
+        resolve_codex_model_id("Opus")
+
+
 def test_cli_model_alias_map_keys_match_known_tiers() -> None:
-    assert set(ALL_CLI_MODEL_ID_BY_TIER) == set(ALL_KNOWN_TIER_NAMES)
+    all_cli_tiers = (*ALL_MODEL_TIERS, THIRD_PARTY_MODEL_TIER)
+    assert set(ALL_CLI_MODEL_ID_BY_TIER) == set(all_cli_tiers)
     assert set(ALL_MODEL_TIERS).issubset(set(ALL_KNOWN_TIER_NAMES))
+    assert ADVISOR_MODEL_TIER in ALL_KNOWN_TIER_NAMES
     assert THIRD_PARTY_MODEL_TIER in ALL_KNOWN_TIER_NAMES
     assert THIRD_PARTY_MODEL_TIER not in ALL_MODEL_TIERS
-    assert all(
-        ALL_CLI_MODEL_ID_BY_TIER[each_tier] for each_tier in ALL_KNOWN_TIER_NAMES
-    )
+    assert all(ALL_CLI_MODEL_ID_BY_TIER[each_tier] for each_tier in all_cli_tiers)
+    assert ALL_CODEX_MODEL_ID_BY_TIER == {
+        ADVISOR_MODEL_TIER: ADVISOR_CODEX_MODEL_ID,
+    }
 
 
 def test_canonical_tier_name_strips_and_normalizes() -> None:

package/_shared/advisor/scripts/tier_model_ids.py

@@ -45,6 +45,9 @@ from advisor_scripts_constants.model_tier_run_validator_constants import (  # no
     UNKNOWN_HOST_PROFILE_ERROR,
     UNKNOWN_LADDER_NAME_ERROR,
 )
+from advisor_scripts_constants.advisor_route_constants import (  # noqa: E402
+    ALL_CODEX_MODEL_ID_BY_TIER,
+)
 
 
 def canonical_tier_name(tier_name: str) -> str | None:
@@ -111,6 +114,27 @@ def resolve_cli_model_id(tier: str) -> str:
     return maybe_model_alias
 
 
+def resolve_codex_model_id(tier: str) -> str:
+    """Return the dated Codex model id for a Codex-backed advisor tier.
+
+    Args:
+        tier: Ladder tier name whose Codex model id should be resolved.
+
+    Returns:
+        The configured Codex model id.
+
+    Raises:
+        ValueError: When ``tier`` is not a known Codex-backed tier.
+    """
+    maybe_canonical_tier = canonical_tier_name(tier)
+    if maybe_canonical_tier is None:
+        raise ValueError(UNKNOWN_LADDER_NAME_ERROR.format(tier))
+    maybe_model_id = ALL_CODEX_MODEL_ID_BY_TIER.get(maybe_canonical_tier)
+    if maybe_model_id is None:
+        raise ValueError(UNKNOWN_LADDER_NAME_ERROR.format(tier))
+    return maybe_model_id
+
+
 def detect_host_profile(
     setting_by_name: Mapping[str, str] | None = None,
 ) -> str:

package/commands/CLAUDE.md

@@ -15,6 +15,7 @@ Slash-command definitions installed into `~/.claude/commands/` by `bin/install.m
 | `pr-comments.md` | `/pr-comments` | Fetches and formats PR review comments for response |
 | `review-plan.md` | `/review-plan` | Reviews the current plan packet against code standards |
 | `right-size.md` | `/right-size` | Checks an implementation against the Right-Sized Engineering rules |
+| `sr-loop.md` | `/sr-loop` | Runs the converging cleanup loop: /simplify passes until clean, then a code-review fix pass |
 | `sum.md` | `/sum` | Generates a formatted session summary for quick pickup in a new session |
 
 ## Format

package/commands/sr-loop.md

@@ -0,0 +1,48 @@
+---
+description: Converging cleanup loop - repeat /simplify until clean, then repeat /code-review --fix until clean
+argument-hint: [PR URL, branch, or blank for the current diff]
+---
+
+Run the converging cleanup loop on the target: `$ARGUMENTS` (blank means the
+current branch's diff). Each phase invokes an existing skill with the Skill
+tool and repeats it until a pass returns zero new findings.
+
+## Phase A — loop /simplify
+
+1. Invoke the `simplify` skill on the target (the same review the user gets
+   from `/simplify <target>`). Let it run its 4-lens fan-out and apply its
+   fixes.
+2. After each pass: run the scoped test suite (test files beside the touched
+   code, not the full repo suite), commit once (`git commit -F <file>`, body
+   written with the Write tool, Co-Authored-By line, 10-minute timeout — the
+   pre-commit gate runs its own tests), and push to the PR head branch. The PR
+   stays draft.
+3. Repeat the invocation. **Skips are sticky:** carry every adjudicated skip
+   forward into the next pass as "already adjudicated — do not re-report: ..."
+   context, or the loop never converges.
+4. Phase A converges when a full pass returns zero new findings. When the
+   previous pass changed only a line or two, a single combined-lens
+   confirmation agent may serve as the final pass.
+
+## Phase B — loop /code-review low --fix
+
+1. Invoke the `code-review` skill with arguments `low --fix` on the same
+   target. Let it report findings and apply its fixes.
+2. After any pass that changed files: test, commit, push as in Phase A.
+3. Repeat until a pass reports zero findings. Phase B usually converges in one
+   pass when Phase A ran first.
+
+## Finish
+
+Report: passes run per phase, commits pushed with hashes, fixes applied, and
+the standing skip list with reasons.
+
+## Constraints (observed under headless runs)
+
+- Run this loop in the main session. A wrapper subagent cannot see the
+  `code-review` skill, and a nested agent's own subagent reports route to the
+  main session instead of back to it.
+- Scope test runs to the touched files; a full-suite run can outlive one
+  foreground tool call.
+- A hung or newly slow test suite is a finding to investigate, not an
+  inconvenience.

package/docs/references/CLAUDE.md

@@ -10,7 +10,8 @@ Pointer documents to external sources, standard terminology, and internal tool o
 | `code-review-enforcement.md` | How the code-review gates work: the two required efforts (push at low, PR creation at xhigh), the stamp bound to the branch-surface hash, the single sanctioned minter, the two-layer stamp-directory guard, and the bypass surfaces the gates leave open |
 | `prose-style-enforcement.md` | How `CLAUDE_PROSE_STYLE_ENFORCEMENT` arms opinionated prose gates (default off) while AskUserQuestion lean-block stays always on |
 | `advisor-tool.md` | Canonical consult bones for any stronger reviewer: when to call, hard rule before first write, how to treat advice; maps to the Anthropic advisor tool |
-| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and how it pairs with `advisor()` |
+| `team-advisor-skill.md` | `/team-advisor` map: sole-consumer warm bind, ref index, and advisor selection |
+| `weak-executor-advisor.md` | Consult profile a below-advisor-tier executor (Sonnet, Haiku) follows on top of `advisor-tool.md`: spawn-prompt steering, context packaging, two-timing rule, consult budget, failure branches |
 
 ## Role
 

package/docs/references/advisor-tool.md

@@ -1,14 +1,14 @@
 # Advisor Tool
 
-Canonical consult timing and weight for any stronger-reviewer path: the native `advisor()` tool, `/team-advisor`, and the shared warm advisor.
+Canonical consult timing and weight for the repository advisor path: `/team-advisor` and the shared warm advisor. Anthropic's advisor documentation supplies the source guidance for packet shape and review timing.
 
 Source bones: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) (Suggested system prompt for coding tasks). API shape, model pairs, cost, and caching live there. This file carries only the call rules a session needs every time.
 
 ## What it is
 
-`advisor()` is a no-parameter review call. The platform forwards the full conversation (task, tool calls, results) to a stronger model. The executor continues with that guidance.
+`/team-advisor` is the repository's advisor implementation. It carries the full first packet explicitly, sends later deltas, and owns the warm Agent/SendMessage or read-only Sol CLI lifecycle.
 
-When `advisor()` is absent, use `/team-advisor` (see `team-advisor-skill.md`).
+See `team-advisor-skill.md` for the bind and lifecycle map.
 
 ## When to call
 
@@ -18,11 +18,11 @@ If the task needs orientation first (find files, fetch a source, see what exists
 
 Also call:
 
-- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not.
+- **When you believe the task is complete.** Before this call, make the deliverable durable: write the file, save the result, commit the change. The call takes time; if the session ends during it, a durable result survives and an unwritten one does not. Ask the advisor to hunt for missing requirements, untested behavior, wrong assumptions, unhandled edge cases, evidence gaps, and early completion claims.
 - **When stuck** — errors recur, approach does not converge, results do not fit.
 - **When considering a change of approach.**
 
-On tasks longer than a few steps, call at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you do not need repeated calls — most value is on the first call, before the approach hardens.
+On tasks longer than a few steps, aim for an early approach consult and a completion review. Reserve a third consult for recovery or reconciliation, and add consults when material new evidence or forks arise. This cadence guides planning and leaves the task free to follow its evidence. Short reactive tasks may use the single consult that best fits the live decision.
 
 Call for design, architecture, and risk questions where you will not touch a file. If the response would be analysis or a recommendation with no other tool calls, call first. That judgment is where a second opinion is highest value. Simple factual lookups and arithmetic do not need a call.
 
@@ -34,7 +34,22 @@ Your first write, edit, or state-changing shell call on a task must be preceded
 
 Give the advice serious weight. If a step fails empirically, or primary-source evidence contradicts a claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it is evidence the test does not check what the advice is checking.
 
-If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw the evidence but may have underweighted it; a reconcile call is cheaper than the wrong branch.
+If your data points one way and the advisor points another: do not silently switch. Surface the conflict in one more call — "I found X, you suggest Y, which constraint breaks the tie?" A reconcile call is cheaper than the wrong branch.
+
+Work a disagreement in this order: keep the observed evidence in the record, name the conflict plainly, ask the advisor which constraint breaks the tie, then act on the reconciled plan.
+
+## Escalation shapes
+
+Four shapes cover how a harder task gets more strength behind it. Route to the one that matches the work, not by default to the advisor.
+
+| Shape | Fits when |
+|---|---|
+| Advisor | The task needs intermittent strategy and review, and one executor keeps the task from start to finish. |
+| Subagent | A piece of the task is a bounded subtask that benefits from its own context and its own loop. |
+| Stronger-model planning phase | The plan needs the strong model's judgment; the fast model can carry it out once written. |
+| Full model switch | Every step of the task needs the stronger tier, not just the hard decisions. |
+
+Spawn a subagent when the work is a delegable bounded subtask. Switch the whole task to the stronger model when every turn needs that tier.
 
 ## Brevity cue
 
@@ -42,10 +57,13 @@ When the consult path supports a free-text brief, append:
 
 `(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)`
 
+Size the ask at roughly 80 percent of the true ceiling; direct address to the advisor lands more reliably than a third-person description.
+
 ## Related
 
 | Doc | Holds |
 |---|---|
 | [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) | API shape, model pairs, cost, caching, full best practices |
-| `team-advisor-skill.md` | Standing warm advisor when `advisor()` is missing |
-| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle, executor paste blocks |
+| `team-advisor-skill.md` | Standing warm advisor for this repository |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, floor walk, lifecycle — a read map routes each bind or consult moment to its `reference/` detail file |
+| `weak-executor-advisor.md` | Consult deltas for an executor spawned below the advisor's own tier |

package/docs/references/team-advisor-skill.md

@@ -1,6 +1,6 @@
 # Team-Advisor Skill
 
-`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. Use it when `advisor()` is absent, or when you want a standing four-signal reviewer across many decision points.
+`/team-advisor` binds one standing warm advisor for this session at the strongest reachable tier. This skill is the selected custom reproduction path for advisor behavior: it forwards explicit packets to a warm Agent/SendMessage advisor or the read-only `codex_sol_advisor.py` path across many decision points.
 
 ## Refs
 
@@ -15,6 +15,6 @@
 
 Follow the call rules in `advisor-tool.md` (orientation first, then consult before substantive work; durable deliverable before the completion consult; stuck or reapproach; long tasks twice).
 
-## Relation to `advisor()`
+## Selected path
 
-`/team-advisor` works with no `advisor()` tool. When both exist: `advisor()` for a fast history-forwarded check; `/team-advisor` for a standing named reviewer consulted at the same cadence.
+`/team-advisor` is the repository's advisor implementation. It provides explicit first-consult packets, delta consults, a standing warm reviewer, and a read-only Sol CLI option.

package/docs/references/weak-executor-advisor.md

@@ -0,0 +1,91 @@
+# Weak-Executor Advisor Profile
+
+Consult profile for an executor spawned below the advisor's own tier — a
+Sonnet or Haiku model carrying an advisor bind. `advisor-tool.md` sets the
+canonical cadence for every consumer; this file adds the deltas a below-tier
+executor needs on top of it.
+
+Source: [Anthropic Advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)
+(Suggested system prompt for coding tasks). The distilled facts behind each
+section live in
+`skills/team-advisor/reference/advisor-docs-review.md`.
+
+## Scope
+
+Applies to any executor running below the advisor's tier. A same-tier or
+stronger executor follows `advisor-tool.md` alone. The paste-ready form of
+this profile is the **Weak-executor add-on** block in
+`~/.claude/_shared/advisor/reference/advisor-block.md`.
+
+## Steering lives in the spawn prompt
+
+The advisor rules sit at the top of the spawn prompt, ahead of every other
+sentence that mentions the advisor — the spawn prompt is the one steering
+surface with measured effect on Sonnet.
+
+## Context packaging
+
+Everything the advisor learns arrives inside the consult. Each consult
+carries its own packet:
+
+- **First consult** — use the complete packet in
+  `~/.claude/_shared/advisor/reference/consult-format.md`: assignment,
+  desired outcome, constraints and exclusions, actions taken in order, real
+  output and current state, decision or blocker, validation evidence,
+  unresolved risks, and load-bearing paths or excerpts.
+- **Later consults** — the delta since the last consult.
+- **Ordering** — stable role and charter text first, volatile detail last.
+
+## Two-timing rule
+
+Two consult moments carry the measured gain:
+
+1. **Early** — after a few exploratory reads land in the transcript, before
+   the first write. This is the hard rule `advisor-tool.md` §Hard rule
+   states for every consumer.
+2. **Final** — after file writes and test output exist to forward. Make the
+   deliverable durable first (write the file, save the result, commit the
+   change), then consult.
+
+## Planner funnel
+
+Consult the advisor before any task-list or planner tool. The advisor's plan
+becomes the task list.
+
+## Consult budget
+
+Aim for two consults per task: early orientation and completion review. Reserve a third for advisory recovery or reconciliation guidance, and add a consult when a material fork produces new evidence. This is a planning target that leaves the task free to follow its evidence.
+
+## Advice weight
+
+Advice is binding absent empirical contradiction. A conflict between the
+executor's own evidence and the advisor's guidance goes back to the advisor
+as a reconcile consult. See `advisor-tool.md` §How to treat advice for the
+full weighing rule.
+
+## Long-run reminder
+
+On a run past roughly 20 advisor-free turns, the executor re-reads its
+advisor rules before the next substantive step — the re-read keeps the
+advisor visible across a long horizon.
+
+## Failure branches
+
+- **Transient advisor failure** — retry once, then carry on with the
+  evidence in hand and record the gap in the result.
+- **Advisor unreachable** — report upward and hold the decision for the
+  owning session; re-binding belongs to that session alone.
+
+## Pairing invariant
+
+The advisor binds at or above the strongest consumer's tier. The floor
+holds at that tier whichever executor joins the pairing.
+
+## Related
+
+| Doc | Holds |
+|---|---|
+| `advisor-tool.md` | Canonical consult cadence, hard rule, brevity cue |
+| `~/.claude/_shared/advisor/advisor-protocol.md` | Host bind, model floor, and the Advisor-block assembly rule |
+| `~/.claude/_shared/advisor/reference/advisor-block.md` | The paste parts — transport preambles, shared core, weak-executor add-on |
+| `skills/team-advisor/reference/advisor-docs-review.md` | Distilled source facts behind each section above |

package/hooks/blocking/test_fable_spawn_gate.py

@@ -11,8 +11,9 @@ field, pass whether or not the marker is present. One test reads
 spawn tool names.
 
 Token pins read the warm-up section and each consuming skill. Two doc-gate
-agreement tests assemble a spawn prompt out of the advisor-protocol wording a
-warm-up bind and a drift re-spawn follow, and run each through the gate, so
+agreement tests assemble a spawn prompt out of the advisor reference wording a
+warm-up bind (``reference/warm-up.md``) and a drift re-spawn
+(``reference/lifecycle.md``) follow, and run each through the gate, so
 wording that stops naming the marker fails here. Two deny-path tests read the
 preview the gate hands the block logger and hold it bounded and scoped to the
 model field.
@@ -64,6 +65,13 @@ _FULL_SONNET_MODEL_ID = "claude-sonnet-4-5"
 _PACKAGE_ROOT = _HOOKS_TREE.parent
 _ADVISOR_PROTOCOL_PATH = _PACKAGE_ROOT / "_shared" / "advisor" / "advisor-protocol.md"
 _ADVISOR_PROTOCOL_TEXT = _ADVISOR_PROTOCOL_PATH.read_text(encoding="utf-8")
+_ADVISOR_REFERENCE_DIR = _PACKAGE_ROOT / "_shared" / "advisor" / "reference"
+_ADVISOR_LIFECYCLE_TEXT = (_ADVISOR_REFERENCE_DIR / "lifecycle.md").read_text(
+    encoding="utf-8"
+)
+_ADVISOR_WARM_UP_TEXT = (_ADVISOR_REFERENCE_DIR / "warm-up.md").read_text(
+    encoding="utf-8"
+)
 _ALL_CONSUMING_SKILL_NAMES = ("team-advisor", "orchestrator", "orchestrator-refresh")
 _ALL_CONSUMING_SKILL_PATHS = tuple(
     _PACKAGE_ROOT / "skills" / each_skill_name / "SKILL.md"
@@ -321,19 +329,18 @@ def test_consuming_skill_names_the_marker_token(skill_path: pathlib.Path) -> Non
     assert FABLE_SPAWN_AUTHORIZATION_MARKER in skill_path.read_text(encoding="utf-8")
 
 
-def _paragraph_starting_at(paragraph_marker: str) -> str:
-    """Return the advisor-protocol paragraph that opens with a marker.
+def _paragraph_starting_at(source_text: str, paragraph_marker: str) -> str:
+    """Return the advisor-doc paragraph that opens with a marker.
 
     Args:
+        source_text: The advisor document text holding the paragraph.
         paragraph_marker: The literal text opening the paragraph.
 
     Returns:
         The paragraph text, running from that marker to the blank line that
         closes it.
     """
-    paragraph_body = _ADVISOR_PROTOCOL_TEXT[
-        _ADVISOR_PROTOCOL_TEXT.index(paragraph_marker) :
-    ]
+    paragraph_body = source_text[source_text.index(paragraph_marker) :]
     paragraph_end = paragraph_body.find(_PARAGRAPH_SEPARATOR)
     if paragraph_end < 0:
         return paragraph_body
@@ -341,7 +348,7 @@ def _paragraph_starting_at(paragraph_marker: str) -> str:
 
 
 def _respawn_spawn_prompt() -> str:
-    """Assemble the spawn prompt a drift re-spawn writes from the protocol.
+    """Assemble the spawn prompt a drift re-spawn writes from the lifecycle doc.
 
     The prompt comes from the re-spawn paragraph alone, so the gate reads
     what that one paragraph tells a session to send.
@@ -349,7 +356,7 @@ def _respawn_spawn_prompt() -> str:
     Returns:
         The spawn prompt text a session following that paragraph sends.
     """
-    return _paragraph_starting_at(_RESPAWN_PARAGRAPH_MARKER)
+    return _paragraph_starting_at(_ADVISOR_LIFECYCLE_TEXT, _RESPAWN_PARAGRAPH_MARKER)
 
 
 def test_respawn_paragraph_prompt_passes_the_gate_at_the_fable_tier() -> None:
@@ -358,7 +365,7 @@ def test_respawn_paragraph_prompt_passes_the_gate_at_the_fable_tier() -> None:
 
 
 def _warm_up_spawn_prompt() -> str:
-    """Assemble the spawn prompt a warm-up bind writes from the protocol.
+    """Assemble the spawn prompt a warm-up bind writes from the warm-up doc.
 
     The prompt comes from the spawn-field prompt bullet alone, so the gate
     reads what that one bullet tells a session to send.
@@ -366,7 +373,7 @@ def _warm_up_spawn_prompt() -> str:
     Returns:
         The spawn prompt text a session following that bullet sends.
     """
-    return _paragraph_starting_at(_WARM_UP_PROMPT_BULLET_MARKER)
+    return _paragraph_starting_at(_ADVISOR_WARM_UP_TEXT, _WARM_UP_PROMPT_BULLET_MARKER)
 
 
 def test_warm_up_prompt_bullet_passes_the_gate_at_the_fable_tier() -> None:

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.10.0",
+    "version": "2.12.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/skills/_shared/advisor/CLAUDE.md

@@ -6,4 +6,4 @@
 
 @~/.claude/_shared/advisor/advisor-protocol.md
 
-Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `tier_model_ids.py`, constants under `scripts/config/`).
+Scripts: `~/.claude/_shared/advisor/scripts/` (`model_tier_run_validator.py`, `codex_sol_advisor.py`, `tier_model_ids.py`, constants under `scripts/config/`).

package/skills/_shared/advisor/scripts/README.md

@@ -4,6 +4,8 @@
 
 @~/.claude/_shared/advisor/scripts/model_tier_run_validator.py
 
+@~/.claude/_shared/advisor/scripts/codex_sol_advisor.py
+
 @~/.claude/_shared/advisor/scripts/tier_model_ids.py
 
 Full tree: `~/.claude/_shared/advisor/scripts/`.

package/skills/grokify/SKILL.md

@@ -43,7 +43,7 @@ The user types `/grokify`, alone or with guidance.
 
 - **Bind once, first:** charter + findings + constraints + plan piped from a temp file into `claude -p --model fable --effort high --output-format json`; parse and save `session_id` from the JSON reply.
 - **Consult:** brief piped into `claude -p --resume <session_id> --model fable --effort high --output-format json`.
-- **ConsultB** If fable is unavailable, use opus with max effort: `claude -p --resume <session_id> --model opus --effort max --output-format json`.
+- **ConsultB** If fable is unavailable, use opus with xhigh effort: `claude -p --resume <session_id> --model opus --effort xhigh --output-format json`.
 - **Signals:** every advisor reply opens with exactly one of ENDORSE, CORRECTION, PLAN, or STOP. CORRECTION and PLAN are actions to take, with a report-back in the next consult on that topic. STOP halts that line of work and surfaces it to the user. When the CLI is unreachable, Grok stops and says so — it never self-endorses in the advisor's place.
 - **Cadence, mandatory:** after planning and before any edit; per phase before implementation (TDD red + approach) and after (diff, tests, acceptance evidence); before every `git commit` and `git push`; on every user-facing fork before asking; on any twice-repeated failure or stall.
 

package/skills/grokify/templates/handoff-template.md

@@ -43,7 +43,7 @@ CONFIRM THESE WITH THE USER FIRST, VIA ASKUSERQUESTION, BEFORE EMBEDDING]
    append the full Established findings, Hard constraints, and Plan sections of this
    document to the same file.
 2. Bind: `claude -p --model fable --effort high --output-format json < <charter-file>`
-2a. If 2 fails, replace fable with opus, effort high to max.
+2a. If 2 fails, replace fable with opus, effort high to xhigh.
 3. The JSON output is an array of events, not one object. Take `session_id` from any
    event; the reply text is the `type == "result"` event's `.result` field. Persist
    `session_id`, the repo root, and the cwd to a state file at once.
@@ -56,7 +56,7 @@ CONFIRM THESE WITH THE USER FIRST, VIA ASKUSERQUESTION, BEFORE EMBEDDING]
    session, not a model failure.
 
 **Consult (every time):** write the brief to a temp file, then
-`claude -p --resume <session_id> --model fable (or opus) --effort high (max for opus) --output-format json < <brief-file>`.
+`claude -p --resume <session_id> --model fable (or opus) --effort high (xhigh for opus) --output-format json < <brief-file>`.
 Act on the reply's opening signal: ENDORSE — proceed. CORRECTION — apply it first;
 your next consult on that topic opens with what happened. PLAN — adopt it; same
 report-back rule. STOP — halt that line of work and surface it to the user. Never

package/skills/orchestrator/SKILL.md

@@ -193,7 +193,7 @@ Touch only: <files or globs>
 Done when: <one mechanical check — a command, a test, a diff scope>
 Return: status, artifact paths, blockers — nothing else.
 
-<host-matched Advisor block from advisor-protocol.md, advisor name filled in>
+<Advisor block assembled per _shared/advisor/reference/advisor-block.md — advisor name filled in>
 ```
 
 - **Size the task by its done-check.** The right task is the largest
@@ -218,9 +218,10 @@ Return: status, artifact paths, blockers — nothing else.
   table picks the definition, and `clean-coder` already holds the code
   discipline. The ticket adds the task, the pointers, and the Advisor
   block only.
-- **The Advisor block is the one pasted paragraph.** It is host-matched
-  at bind time and written to be self-contained (the protocol's Advisor
-  block section) — paste it; do not point at it.
+- **The Advisor block is pasted, assembled text.** Assemble it at bind
+  time from the parts in
+  [`_shared/advisor/reference/advisor-block.md`](../../_shared/advisor/reference/advisor-block.md)
+  and paste the assembled text itself into the ticket.
 
 ## Workflow Agent Routing