@event4u/agent-config 9.10.0 → 9.12.0

package/agents/templates/.ai-council.yml.example

@@ -0,0 +1,481 @@
+# --- AI Council (external second-opinion network) ---
+#
+# WHERE THIS FILE GOES: copy it to the USER-GLOBAL path
+#   ~/.event4u/agent-config/settings/.ai-council.yml
+# and edit it there. This is the ONLY location the council reads (ADR-104,
+# superseding ADR-093) — one global file serves every project, worktree,
+# and CWD. Do NOT place it in a project's `agents/` tree: the project tree
+# is never searched and a `.ai-council.yml` found there is ignored. The
+# only other accepted source is an explicit absolute path in the
+# `$AI_COUNCIL_CONFIG` env var (tests / power users).
+#
+# When enabled, the /council command lets the agent poll independent
+# external models (Anthropic, OpenAI, Gemini, xAI, Perplexity) for a
+# neutral critique of a roadmap, diff, prompt, or file set. Council
+# members never see the host agent's reasoning — only the artefact + a
+# neutral system prompt.
+#
+# Tokens are NEVER stored here. Keys live in 0600 files under
+# ~/.event4u/agent-config/<provider>.key (installed via
+#   bash scripts/install_anthropic_key.sh
+#   bash scripts/install_openai_key.sh
+# for providers with an installer) or in environment variables. The
+# legacy ~/.config/agent-config/<provider>.key tree is read as a
+# fallback. The `api_key_ref:` field below points at one of those —
+# never at the raw secret. See docs/contracts/ai-council-config.md for
+# the full schema.
+#
+# Cost note: every consultation makes real, paid API calls. The
+# autonomy directive does NOT silently spend tokens — the /council
+# command always asks before invoking, even under autonomy: on.
+
+# Master switch (true, false). REQUIRED — the loader has no default for it,
+# so this file's value is the only value.
+#
+# This example ships `true`, and two members below ship `enabled: true`.
+# That is deliberate: the file's job is to be a WORKING starter, and a
+# starter that consults nobody teaches nothing. But be clear about what
+# copying it means — installing a key is not the same as wanting the agent
+# to spend money on it, so review the `members:` block before you copy,
+# and set `enabled: false` on anything you do not want called.
+#
+# `agent-config doctor --check detection` shows, per provider, what this
+# machine detected AND whether it is allowed to spend — so the gap between
+# "could work" and "may spend" is visible rather than mysterious.
+enabled: true
+
+# Per-invocation defaults. Each member may override `mode:` below.
+defaults:
+  # Default transport mode for every member (overridable per-member
+  # below, and per-invocation via `/council mode:<x>`).
+  #
+  #   manual = copy & paste — the human transports prompt + reply
+  #            between the agent and an external chat surface. Free,
+  #            no key.
+  #   api    = SDK call against a stored key, per-token billing.
+  #   cli    = shell out to a locally-installed provider CLI under the
+  #            user's subscription auth (Claude Pro/Max, ChatGPT
+  #            Plus/Pro, Google Gemini, etc.). Spend is covered by the
+  #            flat-rate subscription, not per-token. `cost_budget.
+  #            max_total_usd` does NOT apply; use `cli_call_budget`
+  #            below to guard subscription quotas.
+  #   auto   = resolve per provider per invocation: the provider's CLI
+  #            binary resolves AND a credential is present -> cli; else a
+  #            key resolves -> api; else unavailable with a one-line
+  #            reason. `manual` is NEVER part of the auto chain (it would
+  #            always "succeed" and silently turn every call into a
+  #            copy-paste request) — it stays an explicit opt-in.
+  #            OPT-IN: `auto` is not the shipped default. Switching to it
+  #            moves spend from per-token dollars onto your subscription
+  #            quota, so it is a decision you take, not one you inherit.
+  #            Set `cli_call_budget` below before you flip it.
+  #
+  # Precedence: invocation flag > per-member mode > defaults.mode >
+  # built-in. Two DIFFERENT defaults sit at the bottom, and they are not
+  # the same thing:
+  #   · omit `defaults.mode` entirely and the loader fills "api" — that is
+  #     what every real config file observes.
+  #   · the resolver's built-in fallback, reached only when no layer at all
+  #     supplies a mode (a settings dict handed straight to the resolver,
+  #     no config file involved), is "manual" — free, no key. A caller who
+  #     named no transport has not asked to spend money.
+  mode: api
+
+  # Default number of debate rounds per /council invocation.
+  #
+  # Round 1 sees the artefact alone. Round 2+ sees the artefact plus
+  # anonymised critiques from the previous round (provider/model
+  # identity stripped per the neutrality Iron Law). Applies identically
+  # to api and manual transports — manual mode runs round 1 across all
+  # members, the host agent consolidates, then round 2 starts with the
+  # anonymised round-1 critiques folded in.
+  #
+  # Default is 2 so council members critique each other at least once
+  # before convergence. The agent does NOT ask "how many rounds?" when
+  # the requested rounds <= min_rounds; pass `rounds:N` on the
+  # invocation (or `--rounds N` to the CLI) to override.
+  min_rounds: 2
+
+  # Higher floor for deep-reasoning artefacts (architecture review,
+  # refactoring proposals, bug-diagnosis runs). Activated when the
+  # consuming rule, skill, or command declares `council_depth: deep`
+  # in its frontmatter, or the user passes `--depth deep` to the CLI.
+  # Effective rounds = max(deep_min_rounds, min_rounds), so this floor
+  # is monotonic — lowering it below `min_rounds` has no effect.
+  # Standard tasks keep `min_rounds`; cost rises only when an artefact
+  # opts in. Set to `min_rounds` to disable the deep tier.
+  deep_min_rounds: 3
+
+  # Per-member output-token budget passed to every API call. The CLI
+  # `--max-tokens` flag overrides this on a single invocation; the
+  # cost estimator uses the same value as its worst-case ceiling.
+  # `0` means "unlimited" — internally widened to the safe provider
+  # ceiling (16384) because Anthropic rejects max_tokens=0. This
+  # template ships a right-sized 4096 as a cost lever: council member
+  # positions rarely exceed it, and the estimator uses this value as
+  # its worst-case ceiling, so a tight default stops the pre-flight
+  # gate over-charging. Raise per-run with `--max-tokens`, bump here
+  # for consistently long syntheses, or set `0` for the full ceiling.
+  max_output_tokens: 4096
+
+  # Retention for `agents/council-sessions/` audit folders. Sessions
+  # older than this are pruned automatically on the next `save()`.
+  # `0` disables pruning (keep forever — disk grows unbounded).
+  session_retention_days: 7
+
+  # Reserved by Phase 0, wired in Phase 7 (/council debate). Maximum
+  # number of debate rounds before the orchestrator refuses to continue
+  # even with --auto-continue. Progressive-disclosure cost gate fires
+  # between every round regardless.
+  debate_max_rounds: 4
+
+# Hard cost ceiling per /council invocation. The orchestrator pauses
+# before any member whose projected spend would breach a cap and asks
+# the user to continue. Each `0` disables that single cap; other caps
+# still apply.
+#
+# Applies to BILLABLE members only. Billing follows the PROVIDER and its
+# credential, never the transport name: `mode: manual` never bills, and
+# `mode: cli` is billable=False for the VENDOR-OFFICIAL CLIs (anthropic,
+# openai, gemini — subscription auth), but stays billable=True for the
+# COMMUNITY wrappers (xai, perplexity), whose CLIs consume the same paid
+# API key as `mode: api`. So `max_total_usd` does NOT gate a vendor CLI
+# member and DOES still gate an xai / perplexity member on any transport.
+# Vendor-CLI subscription quotas are guarded by `cli_call_budget` below.
+#
+# Prices come from agents/.agent-prices.md (gitignored, refreshed weekly
+# by `python3 scripts/update_prices.py`; bootstrapped from
+# scripts/ai_council/_default_prices.py on first run).
+cost_budget:
+  max_input_tokens: 500000
+  max_output_tokens: 200000
+  max_calls: 50
+  max_total_usd: 20.0
+
+# Phase 8 — Debate cost-visibility + hard refusal cap.
+#
+# `max_cost_usd` is the unconditional refusal cap. When the pre-flight
+# high-end estimate (expected × 1.20 over-run buffer) exceeds the cap,
+# `/council debate` refuses to start — the user must lower `--rounds`,
+# drop members, or raise the cap explicitly. No --proceed-anyway override.
+# Set to 0 to disable the cap (not recommended).
+#
+# `cost_disclosure.mode` ∈ {"always", "above_threshold", "off"}:
+#   always           — emit the disclosure block before every debate.
+#   above_threshold  — emit only when expected_usd > threshold_usd.
+#   off              — power-user opt-out; the refusal cap still fires.
+# `cost_disclosure.show_per_member` toggles the per-member breakdown.
+#
+# Per-lens override for analysis / default (cheap lenses default to off):
+#   lenses:
+#     analysis:
+#       cost_disclosure:
+#         mode: above_threshold
+#         threshold_usd: 0.50
+debate:
+  max_cost_usd: 5.00
+  cost_disclosure:
+    mode: always
+    threshold_usd: 1.00
+    show_per_member: true
+
+# Per-day call-count guard for `mode: cli` members. The standard
+# `cost_budget` block skips CLI calls because they are billable=False —
+# but provider subscriptions still carry their own quotas (Claude Pro
+# 5h windows, ChatGPT Plus message caps, Gemini free-tier per-day
+# limits). Opt into a per-provider cap; default unset = unlimited from
+# this loader's perspective.
+#
+# Counter state persists at ~/.event4u/agent-config/cli-calls.json
+# with daily UTC reset. Wired by Phase 1 of the CLI-transport roadmap.
+#
+# SHIPPED POPULATED, deliberately: `mode: auto` prefers the cli rung, so
+# shipping that path with no quota guard would miss the point. The caps
+# below are sized from the worst case one invocation can cost — a deep
+# debate is at most `debate_max_rounds` (4) calls per member — so 24
+# permits roughly six full deep debates per provider per day before the
+# guard fires. That is well inside a Pro-tier window while still bounding
+# a runaway loop, and failures count too (a wedged CLI cannot burn the
+# whole budget retrying). Gemini's free tier is the tightest, hence the
+# lower cap. Raise them if you consult heavily; `council:quota` reports
+# usage and `council:quota --reset` clears the day.
+cli_call_budget:
+  max_calls_per_day:
+    anthropic: 24
+    openai: 24
+    gemini: 16
+  # Warn once usage crosses this fraction of a cap (0..1).
+  warn_at: 0.8
+
+# Per-member configuration — you decide what may spend; detection tells
+# you what is already here.
+#
+# DON'T hand-audit this block. Run:
+#
+#   agent-config doctor --check detection
+#
+# It reports, per provider: detected · authenticated · auth source ·
+# billing class · enabled-in-config, the transport `mode: auto` would
+# pick, and a one-line fix for anything unusable. Everything a comment
+# here used to have to explain — which binary, whether a key resolves,
+# whether the CLI is logged in, whether spend is metered or on your
+# subscription — that command answers against YOUR machine.
+#
+# What stays your call is the last column: `enabled`. Detection reports
+# capability; it never grants permission. A provider can be fully
+# detected and still sit at `enabled: false`, and that is a recorded
+# decision, not a misconfiguration — `doctor` prints the exact one-line
+# edit when you want to change it.
+#
+# The three fields:
+#   model:        which model receives the query.
+#   api_key_ref:  a 0600 key file (`file:<name>` — relative paths resolve
+#                 under ~/.event4u/agent-config/, legacy
+#                 ~/.config/agent-config/ read as a fallback) or an env
+#                 var (`env:<VAR>`). Raw keys here are a hard validation
+#                 error. Required for mode: api; optional for cli /
+#                 manual / auto (those may authenticate via the CLI).
+#   mode:         overrides defaults.mode for this member only.
+#   binary:       absolute path to the provider's CLI — only valid when
+#                 the effective mode is `cli` or `auto`. Omit it and the
+#                 default binary name is resolved on $PATH.
+#
+# --- Low-impact fast-path opt-in (Phase 11, default OFF) ---
+# `decision_resolution.classes.low_impact.mode` (see below) defaults
+# to `agent` — low-impact questions resolve on the host and the
+# council never sees them. Routing low-impact to the council is an
+# EXPLICIT TWO-KNOB OPT-IN:
+#   1. flip the class to `mode: council` in `decision_resolution`
+#   2. set `participate_low_impact: true` on each member that should
+#      run on the fast-path (default `false`, per-member opt-in)
+# Missing either knob → fast-path stays unavailable; the loader
+# warns and the resolver falls back to `agent` (or escalates to the
+# user when confidence is below the threshold). See
+# docs/contracts/ai-council-config.md § "Low-impact council opt-in"
+# for the worked example, validation behaviour, and transparency
+# markers.
+members:
+  anthropic:
+    enabled: true
+    model: claude-sonnet-4-5
+    api_key_ref: file:anthropic.key
+    # mode: cli                          # use subscription auth (Claude Pro/Max) — free, see cli_call_budget above
+    # binary: /usr/local/bin/claude      # only valid when mode == cli
+    # Phase 7 — size-fit downgrade ladder (smallest → largest). The
+    # active `model:` above must appear on this list. When the size
+    # classifier flags a request as oversized, it suggests the next
+    # rung *down*; the top rung is the default for complex prompts.
+    model_ladder:
+      - claude-haiku-4-5
+      - claude-sonnet-4-5
+      - claude-opus-4-5
+    # Prompt caching (GA — no beta header) is ON by default: the stable
+    # system + artefact prefix is sent as a cache-controlled block, so
+    # members 2..N in a round (and round-2+ within the 5-min TTL) read
+    # it at ~0.1x input cost. Kill-switch — uncomment to disable:
+    # prompt_cache: false
+    # Phase 4 (road-to-cache-economy) — TTL tier for both breakpoints.
+    # '5m' is the permanent default; do NOT set '1h' without first
+    # confirming the falsification condition in
+    # docs/contracts/ai-council-config.md § prompt_cache.ttl.
+    # prompt_cache:
+    #   ttl: 5m
+    # Phase 11 — opt this member in to the lightweight-QA fast-path.
+    # Only opted-in members run when a `low_impact` question routes
+    # to `council`. Loader default is false, and this example ships
+    # false to match: the fast-path bypasses the standard fan-out, so
+    # pre-flipping a consent knob on the user's behalf is exactly the
+    # thing the master-switch note above warns against. The OTHER knob
+    # (`decision_resolution.classes.low_impact.mode`) also defaults to
+    # `agent`, so the fast-path stays unavailable until you flip both.
+    participate_low_impact: false
+
+  openai:
+    enabled: true
+    model: gpt-4o
+    api_key_ref: file:openai.key
+    # mode: cli                          # use subscription auth (ChatGPT Plus/Pro via Codex CLI) — free
+    # binary: /usr/local/bin/codex       # only valid when mode == cli
+    # Phase 7 — size-fit downgrade ladder (smallest → largest). The
+    # active `model:` above must appear on this list.
+    model_ladder:
+      - gpt-4o-mini
+      - gpt-4o
+      - gpt-4.1
+    # See the anthropic member above — ships false, loader default false.
+    participate_low_impact: false
+
+  gemini:
+    enabled: false
+    model: gemini-2.5-pro
+    api_key_ref: env:GEMINI_API_KEY
+    # mode: cli                          # use Google account (free-tier limits apply) — free
+    # binary: /usr/local/bin/gemini      # only valid when mode == cli
+
+  xai:
+    enabled: false
+    model: grok-4
+    api_key_ref: env:XAI_API_KEY
+    # mode: cli                          # community `grok` CLI (Superagent) — ergonomic shortcut, NOT a billing change.
+    # binary: /usr/local/bin/grok        # The CLI consumes XAI_API_KEY and remains billable=True;
+    #                                    # cost_budget.max_total_usd STILL applies. Opt-in only.
+
+  perplexity:
+    enabled: false
+    model: sonar-pro
+    api_key_ref: env:PERPLEXITY_API_KEY
+    # mode: cli                          # community `perplexity` CLI — ergonomic shortcut, NOT a billing change.
+    # binary: /usr/local/bin/perplexity  # The CLI consumes PERPLEXITY_API_KEY and remains billable=True;
+    #                                    # cost_budget.max_total_usd STILL applies. Opt-in only.
+
+# Thinking-style advisors (replace-mode). When any `advisors.<key>.enabled:
+# true`, the orchestrator REPLACES that advisor's `member:` plain-member
+# call with an advisor-persona call on the same provider. Plain calls
+# fire only for providers whose enabled member is NOT the target of an
+# active advisor.
+#
+# Per-advisor fields:
+#   enabled: <bool>      — off by default; opt-in per advisor.
+#   member:  <provider>  — required; which enabled provider runs this
+#                          advisor (validation fails closed if the named
+#                          member is missing or disabled).
+#   model:   <string>    — optional; overrides the member's plain model
+#                          for this advisor call only. Falls back to the
+#                          member's `model:` when omitted.
+#
+# Persona files live under .agent-src.uncondensed/personas/advisors/
+# and ship with the package; the orchestrator loads them from
+# dist/agent-src/personas/advisors/<key>.md (condensed projection) at call
+# time. See personas/advisors/ + docs/contracts/ai-council-config.md.
+advisors:
+  contrarian:
+    enabled: false
+    member: anthropic
+    # model: claude-opus-4   # uncomment to pin a specific model
+  first-principles:
+    enabled: false
+    member: anthropic
+  expansionist:
+    enabled: false
+    member: openai
+  outsider:
+    enabled: false
+    member: openai
+  executor:
+    enabled: false
+    member: anthropic
+
+# Consensus-scoring round (Phase 4 / F3). After the final deliberation
+# round and before synthesis, members score each other's anonymised
+# findings (1-10 + agree/disagree + one-line reason). The renderer
+# buckets findings by consensus strength:
+#
+#   strength > strong_threshold      → "Strong Consensus" (top of output)
+#   minority < strength ≤ strong     → "Findings" (default body)
+#   strength ≤ minority_threshold    → "Minority Views" (footer, kept)
+#
+# Cost: one extra inference call per member per consultation. The
+# `council:estimate` command accounts for this when `enabled: true` and
+# the active lens is in `lenses`. Default off — opt in deliberately.
+consensus_scoring:
+  enabled: false
+  strong_threshold: 0.7
+  minority_threshold: 0.4
+  lenses:
+    - analysis
+
+# Peer-review pass (Phase 5 / F1, anonymous peer review). After the
+# final deliberation round and before synthesis, each member sees the
+# OTHER members' anonymised outputs (Response-A, Response-B, …) and
+# returns a critique focused on:
+#
+#   - Strongest response (and why)
+#   - Weakest blind spot
+#   - What everyone missed
+#
+# Provider/model identity is stripped (Iron Law of Neutrality); advisor
+# personas (Phase 6) are preserved as signal. The synthesis template
+# gains a "Peer-Review-Surfaced Blind Spots" slot.
+#
+# Cost: one extra inference call per billable member per consultation.
+# Opt-in per R2 verdict — default off. Activated either via this flag
+# or the `--peer-review` CLI flag.
+peer_review:
+  enabled: false
+
+# Council-necessity classifier (Phase 6). Heuristic pre-flight that
+# decides whether the prompt actually warrants a council deliberation
+# before any member fires. Three verdicts drive three exit paths:
+#
+#   necessary  / borderline → proceed (council runs)
+#   unnecessary             → skip (agent) or educate (user_explicit)
+#
+# The classifier is shape-based (word-boundary regex over trigger
+# buckets) — fast, deterministic, no LLM pre-flight cost. False
+# positives on `necessary` are preferable to false negatives; the
+# educate path lets the user override a wrong `unnecessary` verdict
+# via `--proceed-anyway`.
+#
+# Modes:
+#   off     = classifier disabled entirely (legacy behaviour)
+#   educate = unnecessary + user_explicit → educate paragraph + exit 2
+#             unnecessary + agent         → silent skip + exit 0
+#   block   = unnecessary → skip on both invocation paths (no override)
+#
+# See docs/contracts/ai-council-config.md for the trigger lists and
+# per-lens override schema (`lenses.<lens>.necessity_classifier.mode`).
+necessity_classifier:
+  enabled: true
+  mode: educate
+
+
+# ── Decision resolution by impact (Phase 10) ────────────────────────────────
+# Five-class impact classifier routes pending agent questions:
+#   trivial         → agent  (naming, whitespace, comments)
+#   low_impact      → agent  (local idioms, DTOs, test extensions)
+#   medium_impact   → council (API shape, contract changes)
+#   high_impact     → user   (LOCKED — security, auth, migrations, billing)
+#   user_required   → user   (LOCKED — explicit "ask me" / "review first")
+#
+# Iron Law: `high_impact` and `user_required` ALWAYS route to the user.
+# Remapping either to `agent` or `council` is rejected at schema load.
+# `confidence_threshold` is the minimum classifier confidence required to
+# keep the configured mode; below it the mode is upgraded one rung
+# (agent → council → user).
+#
+# See docs/contracts/ai-council-config.md for the trigger lists and the
+# Iron-Law clause.
+decision_resolution:
+  enabled: true
+  classes:
+    trivial:
+      mode: agent
+      confidence_threshold: 0.6
+    low_impact:
+      mode: agent
+      confidence_threshold: 0.6
+    medium_impact:
+      mode: council
+      confidence_threshold: 0.6
+    high_impact:
+      mode: user            # LOCKED — Iron Law
+      confidence_threshold: 0.6
+    user_required:
+      mode: user            # LOCKED — Iron Law
+      confidence_threshold: 0.6
+
+  # Phase 11: lightweight-QA fast-path. Hard caps for `low_impact`
+  # resolutions that route to `council`. Cuts latency + spend by
+  # narrowing the fan-out to opted-in members only and stripping
+  # debate. Multi-round is structurally forbidden — `max_rounds`
+  # MUST stay 1 (the loader rejects any other value).
+  #
+  # Opt members in via `members.<name>.participate_low_impact: true`
+  # below. With no opt-in, fast-path is unavailable and the caller
+  # falls back to the standard council path or escalates to user.
+  fast_path:
+    max_members: 2          # 1 or 2 only — wider fan-out belongs to standard council
+    max_rounds: 1           # LOCKED — Iron Law of the fast-path
+    max_tokens: 2500        # combined input + output budget per resolution
+    max_cost_usd: 0.05      # USD ceiling per resolution
+