@event4u/agent-config 8.12.0 → 8.13.0

package/docs/contracts/ai-team-config.md

@@ -0,0 +1,191 @@
+---
+stability: beta
+keep-beta-until: 2026-10-10
+---
+
+# AI-Team Config (`ai_team` block)
+
+**Purpose.** Lock the schema, validation, and quota rules for the `/team`
+cross-model review family — one strong external model (via the codex CLI,
+subscription-authed) reviewing inside the repo. Team mode is the **depth**
+complement to the council's **breadth**; this contract is the boundary that
+prevents drift across the settings template, the loader, the `/team`
+wrappers, and the quota counter.
+
+**Audience.** Authors of `src/scripts/ai_team/config.ts`, the `/team`
+command family, the doctor `team` section, and the setup wizard. Also
+reviewers checking that new team features keep the schema intact.
+
+**Status.** Internal-locked. Changes require a contract version bump and a
+revision entry in the consuming roadmap.
+
+## File location
+
+Unlike the council (ALWAYS user-global `.ai-council.yml` — see
+[ai-council-config.md](ai-council-config.md)), the `ai_team` block lives in
+the **project settings cascade**:
+
+```
+<project>/.agent-settings.yml   →   ai_team: { … }
+```
+
+read via `load_agent_settings` (`src/scripts/_lib/agent_settings.ts`) and
+validated by `src/scripts/ai_team/config.ts:load_ai_team_config`. Team mode
+is a per-project posture (default-off), not a per-developer credential
+store — the codex CLI carries the subscription auth itself, so there is
+nothing secret to centralize. The shipped defaults live in
+`src/config/agent-settings.template.yml` and are mirrored by the wizard
+schema (`src/server/schemas/settings.ts`, enforced by the schema↔template
+parity test).
+
+## Schema
+
+```yaml
+ai_team:
+  enabled: <bool>                 # master switch, default false
+  model: <string>                 # default 'auto'
+  allow_delegate: <bool>          # second opt-in for the write path, default false
+  max_calls_per_day: <int >= 0>   # default 50; counts into the shared openai bucket
+  suppress_setup_hint: <bool>     # default false; cosmetic wizard-hint suppression
+```
+
+| Key | Type | Default | Semantics |
+|---|---|---|---|
+| `enabled` | bool | `false` | Master switch. `false` = `/team` commands are never suggested and every invocation refuses with an enable pointer — byte-identical to pre-feature behavior. `true` = the family is live; per-command gates below still apply. |
+| `model` | string | `'auto'` | Model handed to the codex CLI. `'auto'` = pass **no** `--model` flag; the codex CLI's own default applies. Any other value passes through **verbatim** as `--model <value>`. |
+| `allow_delegate` | bool | `false` | Second opt-in for the **only** wrapper that delegates write access (`/team:delegate`). Refuses with an enable pointer until BOTH `enabled` and `allow_delegate` are `true`. |
+| `max_calls_per_day` | int ≥ 0 | `50` | Per-day ceiling on team calls, read against the **shared** `cli_call_budget` openai bucket (see § Quota). `0` blocks all team calls. |
+| `suppress_setup_hint` | bool | `false` | Suppress the one-line wizard/init recommendation to install the codex plugin on Claude-Code hosts. Cosmetic only. |
+
+### Why `model: 'auto'` instead of a pinned ID
+
+A hardcoded model ID rots silently (the council's own CLI default is a
+deliberate, documented *pin* — `DEFAULT_OPENAI_CLI_MODEL` in
+`src/scripts/ai_council/clients.ts`, see
+[ai-council-config.md](ai-council-config.md)). Team mode inverts that:
+under a subscription the *strongest* available model is the rational
+default, and only the codex CLI knows what that currently is. `'auto'`
+therefore delegates the choice to the CLI; a set value is a user pin and
+passes through verbatim — the loader never rewrites or "corrects" it.
+
+**Future keys:** `review_gate` (managed, loop-bound governance of the
+plugin's Stop-hook Review Gate) is reserved for a later team-mode phase
+(Phase 4). Do not add it — or any other key — ahead of its phase; the
+loader rejects unknown keys today by design.
+
+## Role semantics — the council-verdict design constraint
+
+Verbatim from the consuming roadmap's council verdict, binding on every
+team-mode phase:
+
+> **Council verdict on team-mode frontmatter (claude-sonnet-4-5 + gpt-4o,
+> 2026-07-12, unanimous REJECT):** skills/commands get NO `team_mode` /
+> role frontmatter. Role semantics belong in the `ai_team` config block +
+> prompt library (reusing subagent-orchestration's implementer/judge frame
+> and status envelope), not smeared across 271 skill files while the
+> feature's role model does not operationally exist. Revisit-if: Phase 2
+> execution turns out to be blocked SPECIFICALLY on artefact-level role
+> metadata — then re-open via decision-revisit-gate, not by silently
+> adding the key.
+
+Operationally: ALL role semantics (builder/reviewer/verifier selection,
+eligibility) live HERE — in this `ai_team` block — plus the prompt
+library, reusing `subagent-orchestration`'s implementer/judge frame and
+its `subagent-status.json` envelope. **No `team_mode`/role frontmatter key
+is added to skill/command/rule schemas.**
+
+## Quota — one subscription, one counter
+
+```
+TEAM CALLS COUNT INTO THE EXISTING cli_call_budget OPENAI BUCKET.
+ONE SUBSCRIPTION, ONE COUNTER. NEVER A PARALLEL COUNTER.
+```
+
+The daily CLI-call counter is already **generic per-provider** — no
+team-specific counting system exists or may be built:
+
+- **State file:** `~/.event4u/agent-config/cli-calls.json`
+  (`CLI_CALLS_FILENAME`, `src/scripts/ai_council/clients.ts:716`), shape
+  `{ date: "YYYY-MM-DD", counts: { <provider>: <int> } }`, resets on UTC
+  date rollover.
+- **Read:** `load_cli_call_counts(path?)` —
+  `src/scripts/ai_council/clients.ts:738`. Returns today's per-provider
+  counts; empty on rollover.
+- **Increment:** `record_cli_call(provider, path?)` —
+  `src/scripts/ai_council/clients.ts:774`. Returns the new total.
+- **Gate + increment on the transport itself:** `CliClient.ask()` checks
+  the counter *before* spawning (`clients.ts` § quota gate, returns
+  `error: 'cli_quota_exhausted'` + a `block_quota` events-log line when
+  exhausted) and records the call *after* — even failed calls count, so a
+  broken CLI cannot burn the budget in a tight loop.
+- **The openai bucket:** `OpenAICliClient` (`clients.ts:1275`) has
+  `name = 'openai'`; council CLI calls and team calls land on the **same**
+  `counts.openai` entry.
+
+A `/team` invocation therefore reuses the existing seams, in preference
+order:
+
+1. **Through the transport** — construct `OpenAICliClient` with
+   `max_calls_per_day: <ai_team.max_calls_per_day>`; the gate, the
+   exhausted-error, the events-log line, and the increment all come for
+   free.
+2. **Direct** (for `/team:status` rendering or a pre-flight check) —
+   `load_cli_call_counts()['openai'] ?? 0` to read,
+   `record_cli_call('openai')` to count. No new helper exists because
+   none is needed; adding a team-side duplicate of this counter is a
+   contract violation.
+
+`ai_team.max_calls_per_day` and the council's
+`cli_call_budget.max_calls_per_day.openai` are two *ceilings* over the
+same *counter*: whichever path a call takes, it increments the one shared
+bucket, and each surface enforces its own configured cap against that
+shared count.
+
+## Validation rules (fail-closed)
+
+`load_ai_team_config` / `build_ai_team_config`
+(`src/scripts/ai_team/config.ts`) raise `TeamConfigError` when:
+
+1. `ai_team` is present but not a mapping,
+2. any **unknown key** appears under `ai_team` (a typo must never
+   silently disable a gate),
+3. `enabled` / `allow_delegate` / `suppress_setup_hint` is not a boolean,
+4. `model` is not a non-empty string,
+5. `max_calls_per_day` is not a non-negative integer (booleans rejected).
+
+An **absent** `ai_team` block is not an error — it yields the defaults
+(`AI_TEAM_DEFAULTS`) and the feature stays off.
+
+## Default-off posture
+
+Every team-mode capability is default-off. With the block absent or
+`enabled: false`, all paths are byte-identical to pre-feature behavior:
+no command suggestions, no wrapper execution, no quota consumption, no
+wizard nagging beyond the single suppressible setup hint.
+`/team:delegate` is doubly gated (`enabled` AND `allow_delegate`).
+
+## No-claims constraint
+
+No public claim about cross-model review quality ("a second model finds
+errors the first never sees", "two strongest models catch each other's
+errors", or any review-lift assertion) may exist anywhere in the tree
+until the pre-registered three-arm defect-finding benchmark has produced
+a verdict bound in CLAIMS.md. Workflow-value prose is allowed; lift
+claims are not. An honest null keeps the feature documented as workflow
+value only.
+
+## Boundary vs. the council
+
+Team mode and the council are complements, not variants — the council's
+neutrality contract is untouched by team mode:
+
+| Axis | Council ([ai-council-config.md](ai-council-config.md)) | Team (`ai_team`) |
+|---|---|---|
+| Shape | N members, breadth | One strong reviewer, depth |
+| Repo access | NEVER (artefact text + neutral preamble only) | Full (reviewer runs inside the working tree) |
+| Config location | User-global `.ai-council.yml` (ADR-104) | Project `.agent-settings.yml` cascade |
+| Default models | Mid-tier, cost-conscious | Subscription's strongest (`model: 'auto'`) |
+| Quota | `cli_call_budget` per provider | Same counter — shared openai bucket |
+
+This link is deliberately one-directional (team → council); the council
+contract does not reference team mode.

package/docs/contracts/command-clusters.md

@@ -45,6 +45,7 @@ column 1 of this table.
 | `council` | 3 | `default` · `pr` · `design` · `optimize` · `analysis` | `council` (legacy default lens) · `council-pr` · `council-design` · `council-optimize`; `analysis` added 2026-05-14 — wrapper for local analysis outputs with a Top-N consensus tail block consumed by `/roadmap create` |
 | `challenge-me` | — | `vision` · `with-docs` | new — Pocock-inspired one-question-at-a-time interview; `vision` is the standard 95%-confidence variant, `with-docs` adds doc/glossary awareness with a session-scoped glossary and load-bearing claim-vs-code verification |
 | `research` | 2 | `deep` · `report` | preliminary-research scaffolder ported from `Weizhena/Deep-Research-skills` (cluster head emits `outline.yaml` + `fields.yaml` against the `research-schema` contract). `:deep` populates per-item JSON in batches with native web-search + JSON-Schema self-validation (no Python runtime); `:report` renders `report.md` directly + optionally emits a `jq` template for deterministic regeneration. `add-items` / `add-fields` intentionally **not** ported — re-run `/research <topic>` to extend the field framework. |
+| `team` | 2 | `review` · `adversarial` · `delegate` · `status` | new 2026-07-12 (road-to-team-mode Phase 2) — cross-model depth review: thin fail-closed delegations to the official codex plugin on Claude-Code hosts under `ai_team` governance ([`ai-team-config`](ai-team-config.md)); default-off (`ai_team.enabled: false`), `delegate` behind the second opt-in `allow_delegate`; internal visibility until the ADR promotion gate |
 | `orchestrate` | — | _(none yet — cluster head only)_ | new — runtime executor for YAML pipelines under `.agent-config/orchestrations/` per the [`orchestration-dsl-v1`](orchestration-dsl-v1.md) contract; chains personas / skills / commands / sub-agents deterministically. Single cluster head; sub-commands deferred until a second verb is needed. |
 | `sync` | 4 | `agent-settings` · `gitignore` · `gitignore-fix` | new cluster 2026-07-08 — absorbs the former single-sub `sync-gitignore` cluster (slug-neutral nests: `sync-agent-settings`, `sync-gitignore`, `sync-gitignore-fix` keep their slugs; the gitignore node keeps its own `fix` sub-dir, mirroring the `agents/user` deep-nest precedent). Bare `/sync` shows the menu. |
 | `ghostwriter` | — | `fetch` · `write` · `list` · `show` · `delete` | new cluster 2026-05-15 — third voice primitive for AI-assisted writing in the public voice of a public figure. Hybrid storage: real-person profiles live consumer-side under `agents/reference/ghostwriter/<slug>.md` (gitignored by default); package source ships only `fictional: true` fixtures. Zero network code in the package — `:fetch` delegates web-fetch / web-search to the host agent. Mandatory disclosure footer on every `:write` output (no opt-out). Schema: [`ghostwriter-schema`](ghostwriter-schema.md). |

package/docs/featured-skills.md

@@ -92,4 +92,4 @@ task lint-featured-skills
 
 CI runs this in `taskfiles/ci-fast.yml`. Stale entries (renamed / removed skill or command) fail the build. See [`scripts/lint_featured_skills.py`](../src/scripts/lint_featured_skills.py) for the matcher.
 
-→ Browse all 271 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 178 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)
+→ Browse all 271 skills: [`dist/agent-src/skills/`](../dist/agent-src/skills/) · all 183 commands: [`dist/agent-src/commands/`](../dist/agent-src/commands/)

package/docs/getting-started-by-role.md

@@ -2,7 +2,7 @@
 
 > Pick the entry that matches what you do day-to-day. Each section names the three skills you will reach for first and shows whether MCP (no terminal) or CLI (terminal) is the simpler install path for that role.
 
-`agent-config` ships 271 skills, 104 governed rules, and 178 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
+`agent-config` ships 271 skills, 104 governed rules, and 183 commands. You do not need all of them. Each role below filters to the slice that pays back in week one; the rest stays available and shows up on demand when a task references it.
 
 > **Taglines at a glance →** [`docs/role-experiences.md`](role-experiences.md) — the one-line pitch per role experience, in one table.
 
@@ -73,6 +73,8 @@ Cinematic-blueprint approach: the agent expands your script into a 12-block scen
 - [`nextjs-patterns`](../dist/agent-src/skills/nextjs-patterns/SKILL.md) — App Router, Server Components, Server Actions, caching.
 - [`quality-tools`](../dist/agent-src/skills/quality-tools/SKILL.md) — PHPStan, Rector, ECS error triage and fix loop.
 
+Cross-model review of the real diff (**team mode**, default off) is documented in [Getting Started § Team mode](getting-started.md#team-mode--cross-model-review-default-off).
+
 **Install path:** **CLI.** Run `npx @event4u/agent-config init --tools=claude-code,cursor` in the project root. MCP works too but loses git / file-system tooling that the IDE-integrated path gives you.
 
 ---

package/docs/getting-started.md

@@ -174,7 +174,37 @@ Your agent now understands slash commands:
 | `/fix quality` | Run and fix all quality checks |
 | `/chat-history import` | Pull a prior session into the current chat (resume) |
 
-→ [Browse all 178 active commands](../dist/agent-src/commands/)
+→ [Browse all 183 active commands](../dist/agent-src/commands/)
+
+---
+
+## Team mode — cross-model review (default off)
+
+Team mode pairs two strong models on one change: one model builds, a
+second reviews the **real diff** in your working tree and hands the
+findings back for a fix round. It is the depth complement to the
+[AI council](../dist/agent-src/skills/ai-council/SKILL.md): the council
+collects many cheap, neutral opinions on an artefact's *text*; team mode
+puts one strong, opinionated reviewer *inside the repo*.
+
+| Axis | Council | Team mode |
+|---|---|---|
+| Repo access | none — members see only the artefact text | full — the reviewer reads the real diff and git state |
+| Shape | breadth — N neutral opinions, one round | depth — one strong reviewer, build→review→fix iteration |
+| Cost model | API-billed members (per-token) | subscription-authed `codex` CLI (runs under your existing plan) |
+
+**Setup.** Run `agent-config doctor --check team` — it verifies the
+`codex` binary + auth and, on Claude Code hosts, the Codex plugin, and
+prints the exact remediation command for anything missing.
+
+**Default off.** Team mode ships disabled (`ai_team.enabled: false` in
+`.agent-settings.yml`); no team command runs and no cross-model call is
+made until you opt in.
+
+**No lift claim.** Whether cross-model team review catches more real
+defects than single-model adversarial self-review is **unproven** — the
+package makes no review-quality claim until the pre-registered benchmark
+has run and its verdict is recorded.
 
 ---
 

package/docs/maintainers/branch-protection.md

@@ -71,6 +71,24 @@ second-writer race to protect against; flip to `true` when there are
 concurrent mergers. `required_pull_request_reviews: null` per the
 bus-factor reality above.
 
+## Operating conditions under `strict: false`
+
+`strict: false` drops the branches-up-to-date requirement, so three
+conditions become merge-time habits the config cannot enforce:
+
+- **The checked commit must not change after green CI.** No post-CI
+  amend or force-push on the PR branch — the config already blocks
+  force-pushes to `main`; the same discipline applies to the head that
+  CI checked: what went green is what merges.
+- **Critical checks must have run on the final head before merge.** A
+  human glance at the checks tab on the PR's latest commit — with
+  `strict: false` GitHub does not re-run required checks when the base
+  moves, so the green you see is only as fresh as the head it ran on.
+- **Auto-merge must not be enabled in a way that merges with pending or
+  failed required checks.** Enable auto-merge only once the required
+  list is complete and green on the final head — never as a
+  fire-and-forget while checks are still queued.
+
 ## Rollback
 
 ```bash

package/docs/proof.md

@@ -27,7 +27,7 @@ evidence pointer, or `task check-claims` fails the build.
 | Claim | Kind | Evidence | Resolves |
 |---|---|---|---|
 | The release process is documented as an inheritable runbook + succession doc, and the project's bus-factor (trailing-90-day distinct human reviewers) is tracked and reported truthfully — currently 1, not implied to be more. | qual | `docs/succession.md#trailing 90 days` | ✅ |
-| 178 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
+| 183 commands. | quant | `src/scripts/check_artefact_count_messaging.ts#Artefact-count messaging gate` | ✅ |
 | A MEASURED-BUT-NOT-SHIPPED experiment — the thin rule projection reduced eager rule load 78,513 → 13,881 GPT-tokens (whole always-loaded projection 98,529 → 33,897, ~65.6%), but FAILED the quality gate (thin win-rate 36.2% vs required 48%) and does not ship; it un-defers only behind `discipline_profile: essential`. Shipped behavior does NOT include this reduction. Method: `agent-config benchmark` over the pinned token baseline; the baseline is the honest "what the user pays if everything loads eagerly", NOT a synthetic full-corpus strawman (council Q4); quality gate per the Phase-0 paired judge run. | quant | `internal/bench/reports/token-baseline.json#eager_rule_load` | ✅ |
 | On a weak host (claude-haiku-4-5) the package produces a significant, placebo-controlled discipline lift on scope/downstream traps; on a strong host the same measurement is a published null — the package transplants discipline a weak model lacks, not model intelligence. | quant | `docs/benchmark.md#weak-host-specific` | ✅ |
 | The non-coding domain skills (finance/founder/ops/content) are forged on TS/PHP and labeled unvalidated until they pass a sourced domain-truth fixture; no public prose implies proven domain correctness, and the validated count is CI-ratcheted. | qual | `src/scripts/domain_soundness_status.ts#checkRatchet` | ✅ |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "8.12.0",
+    "version": "8.13.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,

package/src/config/agent-settings.template.yml

@@ -629,6 +629,46 @@ worktrees:
 #
 # See `docs/contracts/ai-council-config.md` for the schema.
 
+# --- AI Team (cross-model strong-pair review — /team family) ---
+#
+# Governs the default-off `/team` capability family: one strong external
+# model (via the codex CLI, subscription-authed) reviews inside the repo —
+# the depth complement to the council's breadth. Schema + validation
+# contract: `docs/contracts/ai-team-config.md`. The loader
+# (`src/scripts/ai_team/config.ts`) rejects unknown keys fail-closed.
+ai_team:
+  # Master switch. false (default) = /team commands are never suggested
+  # and every invocation refuses with an enable pointer; true = the
+  # family is live (individual gates below still apply).
+  enabled: false
+
+  # Model handed to the codex CLI. 'auto' (default) = pass NO --model
+  # flag, the codex CLI's own default applies — this tracks the
+  # subscription's current strongest model instead of pinning a stale
+  # ID. Any other value passes through verbatim as `--model <value>`.
+  model: auto
+
+  # Second opt-in for the ONLY wrapper that delegates write access
+  # (/team:delegate → the plugin's native-Codex worker). false (default)
+  # = delegate refuses with an enable pointer even when ai_team.enabled
+  # is true. Both keys must be true before delegation is reachable.
+  allow_delegate: false
+
+  # Per-day cap on team calls. Team calls count into the EXISTING
+  # cli_call_budget openai bucket (~/.event4u/agent-config/cli-calls.json,
+  # daily UTC reset) — one subscription, one counter, never a parallel
+  # count. This key is the team-side ceiling read against that shared
+  # bucket. 0 = block all team calls; raise if you review heavily.
+  max_calls_per_day: 50
+
+  # Suppress the one-line wizard/init recommendation to set up the codex
+  # plugin on Claude-Code hosts. Cosmetic only — never changes behavior.
+  suppress_setup_hint: false
+
+  # NOTE for future keys: `review_gate` (managed loop-bound governance of
+  # the plugin's Stop-hook Review Gate) lands in a later team-mode phase
+  # (Phase 4) — do not add it here ahead of that phase.
+
 # --- Onboarding ---
 #
 # Tracks whether the initial setup flow (/onboard) has been completed

package/src/scripts/_cli/cmd_doctor.ts

@@ -29,7 +29,7 @@
  * scope · global-binary · claude-plugin · stale-orphans · manifest-integrity ·
  * lockfile-freshness · bridge-drift · mcp-mode · mcp-beta-readiness ·
  * offline-readiness · python-runtime · humanizer-runtime · tier-usage-readiness ·
- * council-cli ·
+ * council-cli · team ·
  * unsupported-combos · wizard-state.
  * Each emits a structured `{id, status, message, remedy}` record with
  * `status` ∈ `ok` / `warn` / `fail` / `skipped` (rendered
@@ -747,6 +747,7 @@ const CHECK_IDS = [
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'team',
     'unsupported-combos',
     'wizard-state',
     'settings-review-pending',
@@ -769,6 +770,7 @@ const GLOBAL_CHECK_IDS: ReadonlySet<string> = new Set([
     'humanizer-runtime',
     'tier-usage-readiness',
     'council-cli',
+    'team',
     'wizard-state',
     'settings-review-pending',
 ]);
@@ -1975,6 +1977,196 @@ function pyFloat(value: number): string {
     return String(value);
 }
 
+// ---------------------------------------------------------------------------
+// team check (road-to-team-mode Phase 1) — codex binary + auth, official
+// codex plugin on Claude-Code hosts, Review-Gate consistency.
+// ---------------------------------------------------------------------------
+
+/**
+ * Codex CLI home — `CODEX_HOME` env override (the codex CLI's own
+ * convention), else `~/.codex`.
+ */
+function _codex_home(): string {
+    const env = (process.env['CODEX_HOME'] ?? '').trim();
+    return env !== '' ? env : path.join(os.homedir(), '.codex');
+}
+
+/**
+ * Codex binary name for the team check — REUSES the council probe's binary
+ * discovery: when a council config exists and declares an enabled cli-mode
+ * `openai` member with a `binary` override, honour it; else the provider
+ * default from `_CLI_PROVIDER_META` (`codex`). Never throws — an unreadable
+ * or invalid council config falls back to the default binary (the council-cli
+ * check owns reporting that problem).
+ */
+function _team_codex_binary_name(project_root: string): string {
+    const default_bin = (_CLI_PROVIDER_META['openai'] as [string, boolean])[0];
+    const { load_council_config, resolve_config_path } = ai_council_config;
+    const council_path = resolve_config_path(project_root);
+    if (!pathExists(String(council_path))) {
+        return default_bin;
+    }
+    let cfg: ai_council_config.CouncilConfig;
+    try {
+        cfg = load_council_config(council_path);
+    } catch {
+        return default_bin;
+    }
+    const member = cfg.members.get('openai');
+    if (member && member.enabled && member.mode === 'cli' && member.binary) {
+        return member.binary;
+    }
+    return default_bin;
+}
+
+/** Settings-flag coercion shared with the tier-usage check (bool or string). */
+function _settings_flag(val: unknown): boolean {
+    if (typeof val === 'boolean') return val;
+    if (typeof val === 'string') {
+        return ['true', 'yes', 'on', '1'].includes(val.trim().toLowerCase());
+    }
+    return false;
+}
+
+/** The `ai_team` block from `.agent-settings.yml` — lenient, `{}` when absent. */
+function _read_ai_team_block(project_root: string): Dict {
+    const settings_file = project_settings_path(project_root);
+    if (!isFile(settings_file)) return {};
+    let content: string;
+    try {
+        content = readText0(settings_file);
+    } catch {
+        return {};
+    }
+    const loaded = yamlSafeLoad(content);
+    if (typeof loaded !== 'object' || loaded === null || Array.isArray(loaded)) return {};
+    const raw = (loaded as Dict)['ai_team'];
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return {};
+    return raw as Dict;
+}
+
+/**
+ * `team` health check — three sub-signals folded into one result:
+ *
+ * (a) codex binary present (council-probe binary discovery reused) AND
+ *     auth present. Auth is a READ-ONLY presence probe of
+ *     `$CODEX_HOME/auth.json` (default `~/.codex/auth.json`) — token
+ *     expiry cannot be validated without a billable call; runtime expiry
+ *     is caught by `OpenAICliClient._AUTH_FAILURE_PATTERNS`.
+ * (b) on Claude-Code hosts (claude binary on PATH or the Claude config dir
+ *     present): the official codex plugin recorded in
+ *     `plugins/installed_plugins.json`. Detection is read-only — doctor
+ *     never writes under `~/.claude/`.
+ * (c) Review-Gate consistency: `ai_team.review_gate.managed` on while the
+ *     loop bound (`max_consecutive_blocks`, Phase 4 — unbuilt) is absent
+ *     → WARN.
+ *
+ * Absent feature ≠ broken feature: with `ai_team` absent or disabled the
+ * check reports ok ("team mode not configured (default-off)"); WARN fires
+ * only on failing sub-signals or inconsistent half-configured states.
+ */
+function _check_team(project_root: string): Dict {
+    const ai_team = _read_ai_team_block(project_root);
+    const enabled = _settings_flag(ai_team['enabled']);
+    const gateRaw = ai_team['review_gate'];
+    const gate =
+        typeof gateRaw === 'object' && gateRaw !== null && !Array.isArray(gateRaw)
+            ? (gateRaw as Dict)
+            : {};
+    const gate_managed = _settings_flag(gate['managed']);
+    const bound = gate['max_consecutive_blocks'];
+    const bound_present = typeof bound === 'number' && Number.isInteger(bound) && bound > 0;
+
+    if (!enabled) {
+        if (gate_managed) {
+            return {
+                id: 'team',
+                status: 'warn',
+                message:
+                    'half-configured: ai_team.review_gate.managed is on but ' +
+                    'ai_team.enabled is false — the gate never runs',
+                remedy:
+                    'set `ai_team.enabled: true` in .agent-settings.yml, or ' +
+                    'remove `ai_team.review_gate.managed`',
+            };
+        }
+        return {
+            id: 'team',
+            status: 'ok',
+            message: 'team mode not configured (default-off)',
+            remedy:
+                'opt in via `ai_team.enabled: true` in .agent-settings.yml, ' +
+                'then re-run `agent-config doctor --check team`',
+        };
+    }
+
+    const remedies: string[] = [];
+
+    // (a) codex binary — council-probe discovery reused.
+    const binary_name = _team_codex_binary_name(project_root);
+    const binary_resolved = shutilWhich(binary_name);
+    const binary_glyph = binary_resolved !== null ? '✅' : '❌';
+    if (binary_resolved === null) {
+        remedies.push('install the codex CLI: `npm install -g @openai/codex`');
+    }
+
+    // (a, cont.) codex auth — presence probe of $CODEX_HOME/auth.json.
+    const auth_path = path.join(_codex_home(), 'auth.json');
+    const authed = pathExists(auth_path);
+    const auth_glyph = authed ? '✅' : '❌';
+    if (!authed) {
+        remedies.push('run `codex login`');
+    }
+
+    // (b) official codex plugin — Claude-Code hosts only.
+    const is_claude_host =
+        shutilWhich('claude') !== null || pathExists(claude_plugin.claude_config_dir());
+    let plugin_str: string;
+    if (is_claude_host) {
+        const plugin_present = claude_plugin.codex_plugin_installed();
+        plugin_str = `codex plugin ${plugin_present ? '✅' : '❌'}`;
+        if (!plugin_present) {
+            remedies.push(
+                'install the official codex plugin: ' +
+                    claude_plugin.CODEX_PLUGIN_INSTALL_HINT.map((c) => `\`${c}\``).join(' then '),
+            );
+        }
+    } else {
+        plugin_str = 'codex plugin — (not a Claude Code host; fallback path applies)';
+    }
+
+    // (c) Review-Gate consistency.
+    let gate_str: string;
+    if (gate_managed && !bound_present) {
+        gate_str = 'review-gate ⚠️ on, loop bound absent';
+        remedies.push(
+            'set `ai_team.review_gate.max_consecutive_blocks` (loop bound; ' +
+                'ships with the Review-Gate governance phase) or set ' +
+                '`ai_team.review_gate.managed: false`',
+        );
+    } else {
+        gate_str = `review-gate ${gate_managed ? 'on' : 'off'}`;
+    }
+
+    const detail =
+        `codex binary ${binary_glyph} (${binary_name}) · ` +
+        `codex auth ${auth_glyph} (${auth_path}) · ${plugin_str} · ${gate_str}`;
+    if (remedies.length > 0) {
+        return {
+            id: 'team',
+            status: 'warn',
+            message: `${remedies.length} team sub-signal(s) failing · ${detail}`,
+            remedy: remedies.join('; '),
+        };
+    }
+    return {
+        id: 'team',
+        status: 'ok',
+        message: `team mode enabled · ${detail}`,
+        remedy: '',
+    };
+}
+
 function _check_unsupported_combos(manifest: Dict): Dict {
     const global_only = new Set(['droid', 'qoder']);
     const bad: string[] = [];
@@ -2257,6 +2449,7 @@ function _run_checks(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        team: () => _check_team(project_root),
         'unsupported-combos': () => _check_unsupported_combos(manifest),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
@@ -2329,6 +2522,7 @@ function _run_checks_no_manifest(
         'humanizer-runtime': () => _check_humanizer_runtime(),
         'tier-usage-readiness': () => _check_tier_usage_readiness(project_root),
         'council-cli': () => _check_council_cli(project_root),
+        team: () => _check_team(project_root),
         'unsupported-combos': () => _skipped_manifest_check('unsupported-combos'),
         'wizard-state': _check_wizard_state,
         'settings-review-pending': _check_settings_review_pending,
@@ -2818,6 +3012,7 @@ export {
     _check_mcp_beta_readiness,
     _check_tier_usage_readiness,
     _check_council_cli,
+    _check_team,
     _check_unsupported_combos,
     _check_wizard_state,
     _check_settings_review_pending,