feat(orchestrator): ship the A/B-tested persona restructure

[SUaDtL]

Summary

Ports the A/B-tested orchestrator persona candidate (issue #609) into core/surface/ORCHESTRATOR.md:

• Hard rules moved to the head of the document (## §3 — Hard rules, physically first).
• A rationalization guard + letter-vs-spirit rule (## §0 — Non-negotiables), with the excuse -> reality table (5 named excuses, e.g. "It looks good.", "Too small for the lane.", "The suite was green earlier.").
• Terminology lock tightened (## §0.1).
• The asking discipline now explicitly governs tier-2/tier-3 redirects, closing the A/B test's one caught defect: "a candidate list still leads with your recommendation and its strongest counter-consideration — pick one without a recommendation is a menu, not a briefing."
• A new "when a decision is the user's, ask it — fully, once" paragraph: lead every ask with a recommendation AND its strongest counter-case.
• A gate-diagnosis doctrine: "A gate that looks wrong is diagnosed, not bypassed" (## §7).
• ## §1 — Activation & startup is deleted from the persona; its instructions ("present it, then await a command" + the two uninitialized-repo routing rules) were already carried by session-start.py's own emitted briefing — confirmed via git blame (routing rules pre-existing, presentation line since 2026-07-12) — so this ships as tests only, no hook production change. §1's third bullet ("repos without the flag never load this persona") is dropped outright — it's self-evident from the hook's own dormancy path and has no new home.

Canonical section numbers are preserved (§0/§0.1/§2/§3/§4-§5/§6/§7) so existing cross-references stay valid (ORCHESTRATOR §3 in decision-lifecycle/SKILL.md, ORCHESTRATOR §7 in dev-mode.md, §6 redirect in COMMANDS.md) — only the physical ordering changed to match what was tested.

Render-diff summary (Part 1.5)

diff persona-B.md plugins/ca/ORCHESTRATOR.md shows exactly:

1. Section renumbering (§0→§3, §1→§0.1, §3→§4/§5, §5→§6, §6→§7) and the two in-prose "§5"→"§6" cross-reference fixes.
2. The single structural hunk from splitting the candidate's one §0 — Hard rules section into canonical §3 (the MUST/MUST NOT bullets) + §0 (the letter-vs-spirit sentence + excuse table) — a --- + new heading inserted, per the template's existing "--- between numbered sections" convention.
3. One line-break move (not a word change): the "routing gap" paragraph's wrap was moved so that phrase stays on one line — the candidate's own wrap split "routing"/"gap" across a newline, which broke test_routing_and_cleanup_surface.py's substring check on all three hosts. Zero word-level change.

No other differences. Host-conditional Paths/Commands blocks (claude/codex/pi) were restored around the candidate's claude-only text — verified byte-identical to the candidate for the claude render (they don't even appear in the diff), and codex/pi's host-notes load instructions (codex-host-notes.md, pi-host-notes.md) and the dev-mode.md/SPRINT.md load instructions survive on all three hosts.

Test results

• python tools/build-surface.py --check / python tools/sync-core.py --check: both OK.
• python -m pytest .github/scripts/test_build_surface.py -q: 40 passed.
• python .github/scripts/test_routing_and_cleanup_surface.py: 19 passed (pins §6 content on all three hosts).
• python .github/scripts/test_ux_conversion.py: 8 obligation groups green.
• Full hook suite (NO_COLOR unset): 10 failed / 1301 passed / 130 subtests. The 10 failures are the pre-existing test_git_hooks.py/test_repo_resolution.py worktree-enforcer-path failures — measured on a clean origin/main checkout before any edit in this branch (10F/1298P/130 subtests); +3 is exactly this PR's new tests, no new failures.
• git diff --check: clean.
• Gates (post-commit, diff base...HEAD): check_badge_consistency.py OK; test_release_trace.py 29 passed; payload_version_gate.py --plugin plugins/ca 2.11.5 -> 2.11.6 OK; payload_version_gate.py --plugin plugins/ca-codex 0.4.4 -> 0.4.5 OK; build-host-packages.py --check --release-guard-base origin/main 0.2.4 -> 0.2.5 OK.
• CI: green after one rerun. Coverage union <os: windows-latest> failed once on farm-dist.test.ts > completes green against the loopback API — a 5000ms per-test timeout on a Windows runner where sibling tests in the same file took 25s and 44s. Reran via gh run rerun --failed; green. This PR touches no JavaScript, no farm.* source, and no vitest configuration, so the bundle test's timing is outside its blast radius.

Mutation proofs

New TestStartupInstructionsHostAware in plugins/ca/hooks/tests/test_session_start.py (3 tests), each against a fake host with distinct command spellings so a hardcoded-claude-string mutant can't pass:

• Mutant 1 (reword the presentation line away): test_initialized_repo_presents_state_then_awaits_a_command -> red, then reverted -> green.
• Mutant 2 (swap cmd_ref('create-context') <-> cmd_ref('decompose')): both test_uninitialized_repo_with_source_routes_to_create_context and test_uninitialized_empty_repo_routes_to_decompose -> red, then reverted -> green.

Both mutants applied to core/pysrc/session-start.py, synced via tools/sync-core.py into the vendored copy the tests import, then reverted with sync-core.py --check confirming a byte-identical restore.

Part 2.3 finding

Both §1 instructions were already implemented in session-start.py before this PR — the uninitialized-repo routing rules (git blame shows pre-#609 era) and the "present this state, then await a {command}" line (blamed to commit eee3949e3, 2026-07-12). No hook production code changed; only tests were added to pin the behavior now that it's the persona's sole carrier of that instruction.

Closes #609

https://claude.ai/code/session_01QjJeSbcwPHwMmd6CEZeagB

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 9867fecc-aa67-4df6-9612-89d49732af67

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}