codex-advisor-board

name	codex-advisor-board
description	Run a customizable cross-vendor advisor board (formerly advisor-panel; that name remains a working alias) through the agent-harness runtime primitive when a high-stakes change needs independent review evidence.

Advisor Board

Use this skill when a plan, implementation diff, release closeout, or other high-stakes artifact needs an independent cross-vendor review board. This skill was formerly named advisor-panel; that name still resolves as an alias, so existing instructions that say "advisor-panel" keep working.

Source Of Truth

The advisor-board (formerly advisor-panel) implementation is owned by agent-harness:

• Runtime primitive: phase_loop_runtime.panel_invoker
• Board model: phase_loop_runtime.advisor_board (seats, boards, resolver, validation)
• Entry points (runnable default): advisor_board.composition.compose_review_board + panel_invoker.invoke_board, exposed as the phase-loop advisor-board <artifact> CLI. The legacy available_panel_legs/invoke_panel/invoke_panel_request stay in place for the governed review/pre-merge gates (unchanged, byte-identical golden).
• Governed workflow integration: phase-loop governed review/pre-merge paths

Do not call dotfiles advisor-panel scripts, copy provider-specific shell scripts, or introduce a separate implementation in the skill body. The skill is a thin operator guide over the runtime primitive.

Boards & Availability-Aware Composition

Named boards live in phase_loop_runtime.advisor_board.presets; the default review board is code-review, a 4-vendor cross-vendor panel — one seat per frontier vendor (grok, claude, codex, gemini), each at its MAXIMUM thinking with a DISTINCT review lens (adversarial / correctness / red-team / alternative-approach).

Composition is AVAILABILITY-AWARE (composition.compose_review_board): it targets 4 independent reviewers (hard floor 3) and NEVER collapses to 1–2 when vendors are down. Each vendor that is both present on PATH AND authenticated gets one lens-distinct seat first; the remaining seats are BACKFILLED onto the available (up + authed) vendors with DIFFERENT lenses. So 2 vendors up still yields a full 4-seat board, and 1 vendor up yields 4 distinct-lens seats on that vendor. The bare advisor-board (default/premerge) board is unchanged — the byte-frozen 3-leg panel.

Three Ways To Feed Material

There are THREE DISTINCT ways to give the panel material. The #114 fix names them accurately: artifact_ref and brief_ref are Read-file-and-stage conveniences, while context_refs is the true by-reference mode.

• Inline (artifact="...") — small material passed as a string, written verbatim into review-bundle.md. A large inline artifact logs a steering warning.
• Read-file-and-stage (artifact_ref="path/to/bundle.md", or a list) — the runtime READS the local file(s) off disk and stages their bytes into review-bundle.md (a single path verbatim; multiple paths under per-file headers). This keeps YOUR context lean, but the file CONTENTS still land in the staged bundle every leg reads. Use it when you WANT the legs to read the material verbatim. artifact_ref wins over artifact if both are given.
• brief_ref="path/to/brief.md" — a Read-file-and-stage path for a large review brief; staged as review-instructions.md. Omit it to use the built-in review/advisory brief.
• TRUE by-reference (context_refs=["path/to/large.pdf", ...], #114) — the runtime stages ONLY a path + metadata manifest (path, size, sha256, MIME/extension, and PDF page count when cheap) plus an instruction telling each leg to OPEN the files with its own local tools. Raw file contents are not read into the bundle or prompt by this runtime path. Use it for LARGE or PRIVATE local material when the selected provider/backing can access the same local file path. A missing/unreadable path fails CLOSED naming the path, unless you pass context_refs_soft_warn=True (logs a warning and emits an UNREADABLE manifest entry). Pathnames and hashes can disclose sensitive metadata, and a leg may disclose file contents after it intentionally inspects a referenced file unless an output policy forbids disclosure.

Bounding A Slow Leg

Legs fan out concurrently, so panel wall-clock ≈ max(leg), not sum. Each leg's default timeout is INPUT-SCALED (~600s floor + ~12s/KB, capped at 1800s): a ~150-line artifact is roughly ~11 min/leg, and a genuinely max-effort frontier review of a large bundle can approach the cap. Pass timeouts_by_leg={"gemini": 300} (or PanelRequest.timeout_seconds_by_leg) to BOUND a slow/stalled leg so it fails ITS leg instead of hanging the whole panel. A transient CLI stall (an empty turn or a "timeout waiting for response" marker) is retried once, but only when it fails FAST, so a retry can never double a slow leg's wall-clock.

Use

Optional governed research

For current external evidence, opt in with ResearchPolicy(enabled=True) on the board. The runtime requires the exact published pmcp==1.20.0 scoped_advisor_audit.v1 capability, creates unique per-seat locks/audits, and exposes only PMCP health/catalog/describe/invoke backed by Firecrawl and Bright Data research tools. It disables Codex native web search/apps, derives success from the completed correlated audit rather than model prose, and emits only privacy-safe tool IDs, statuses, source hashes, and digests. Claude still runs only through the subscription TUI adapter—never an API, SDK, direct HTTP call, gateway backing, or native Task Agent. Gemini/agy, Grok, Omnigent, native-host, and custom-spawn research seats fail closed as research_profile_unenforceable.

1. Prefer the repo's governed phase-loop path when reviewing phase execution or pre-merge work.
2. For a standalone smoke or diagnostic, run phase-loop advisor-board <artifact> (or, in-process, compose with compose_review_board and pass the material's path via artifact_ref to phase_loop_runtime.panel_invoker.invoke_board).
3. Require every leg to end with AGREE, PARTIALLY AGREE, or DISAGREE.
4. Treat EMPTY, TIMEOUT, ERROR, DEGRADED, and UNAVAILABLE as structured evidence, not successful reviews.
5. Keep provider API keys and custom authorization headers out of the environment; the runtime strips known API-key variables and request-header overrides and uses local subscription CLIs.
6. Every Fable or Opus seat requires the homebrew Claude Code self-PTY adapter after claude auth status --json proves a first-party claude.ai subscription. tui_backing_required, subscription_auth_unproven, and tui_adapter_required are unavailable seats, never invitations to substitute a gateway, API, or native Task Agent.

Claude Subscription TUI Boundary

Fable and Opus have one execution route: the homebrew installed Claude Code TUI in a self-allocated PTY. An alternate backing fails before gateway access. The launch pins the exact requested model, disables fallback-model selection, supplies run-isolated settings with no API-key helper, and uses an environment scrubbed of credentials, custom request headers, alternate endpoints, and cloud-provider selectors. The auth probe accepts only a logged-in, first-party claude.ai subscription. Identity fields and raw probe output are not retained.

On a headless non-Claude host, the self-PTY route remains valid. Inside Claude Code, where a nested TUI cannot be driven safely, the seat returns UNAVAILABLE with detail="tui_adapter_required". Do not fill it through the host's Task/subagent primitive; retry the board from a host where the TUI adapter can run.

Today's TUI adapter has no typed classifier-refusal capability, so refusal-looking text never triggers fallback. A future typed adapter may permit one Opus TUI retry only for independently attested defensive-security work; the result remains degraded/fallback-attributed, and a second refusal fails closed. The legacy native-fill descriptor remains only for explicitly custom, non-governed integrations.

Standalone Smoke Shape

from phase_loop_runtime.advisor_board.composition import compose_review_board
from phase_loop_runtime.panel_invoker import invoke_board

# Availability-aware by default: compose_review_board seats only vendors that are
# BOTH on PATH and authenticated (unauthed vendors are dropped and backfilled).
board = compose_review_board()
result = invoke_board(board, "", artifact_ref="path/to/bundle.md")
for leg in result.legs:
    print(leg.seat_key, leg.status)