@event4u/agent-config 5.10.1 → 6.1.0

package/dist/agent-src/skills/ai-council/SKILL.md

@@ -0,0 +1,912 @@
+---
+model_tier: inherit
+name: ai-council
+description: "Use when polling external AIs (OpenAI, Anthropic) outside the host session for a neutral second opinion on a roadmap, diff, prompt, or file set — or 'cross-check with another model'."
+domain: process
+meta_skill: true
+workspaces:
+  - agent-config-maintainer
+packs:
+  - meta
+---
+
+<!-- cloud_safe: degrade -->
+
+> **Experimental.** AI Council is not yet validated by external users. API costs apply per consultation.
+
+# ai-council
+
+## When to use
+
+* The host agent has drafted a roadmap, plan, or design and wants an
+  **external** critique that is not biased by its own framing.
+* The user asks "what would Claude / GPT say about this?" or invokes
+  `/council`.
+* A PR diff or commit range needs a second-opinion review beyond the
+  internal four-judge pass.
+* A free-form proposal benefits from being challenged by an outside
+  reviewer before it calcifies into work.
+
+Do NOT use when:
+
+* The decision is internal-only and budget matters more than diversity
+  of opinion → use `subagent-orchestration` (in-session, no network,
+  no money).
+* The artefact contains secrets that cannot be redacted with the
+  bundler's pattern set → ask the user before sending.
+* The user has not configured any council member → state that and stop;
+  do not silently fall back to anything.
+
+## When NOT to invoke — necessity self-check
+
+Phase 6 necessity classifier (see
+[`ai-council-config § Necessity classifier`](../../../docs/contracts/ai-council-config.md))
+runs as pre-flight gate inside CLI, skips council when prompt looks
+like routine work. Route around it BEFORE gate fires so user never pays
+classifier-pause cost on request that obviously did not need council.
+
+Skip council, stay in-session for:
+
+* **Bugfix shape** — stack trace, error, crash, failing test, "broken",
+  regression. Use `systematic-debugging` or `bug-investigate`.
+* **Syntax / format / lint** — `typo`, `formatting`, `lint`, `indent`,
+  `import order`, simple rename. Use language skill directly
+  (`php-coder`, `eloquent`, `nextjs-patterns`).
+* **Single-file implementation** — "this function", "this method",
+  "this file", "one-liner", "small change", "add a getter". Use
+  language skill directly.
+* **Documentation lookup** — "what is X", "how does Y work", "example
+  of Z", "syntax of W". Use `codebase-retrieval` or docs skill, never
+  council.
+
+Invoke council when:
+
+* **Architectural / structural** — system boundaries, coupling,
+  refactor strategy, migration plan, rewrite vs redesign.
+* **Multi-axis trade-off** — stakeholders disagree; competing
+  alternatives need weighing; "pros and cons" is the actual ask.
+* **Strategic / direction** — "should we …", "shall we …", roadmap
+  shape, long-term technical direction.
+* **Explicit ambiguity** — user wrote "unsure / uncertain / ambiguous
+  / second opinion / sanity check".
+
+Agent orchestration MUST call `council_cli` with `--invocation agent`
+so gate can skip silently on routine requests. User-typed `/council`
+keeps default (`--invocation user_explicit`); user gets educational
+message + `--proceed-anyway` override path. Mode `block` ignores
+`--proceed-anyway` by design — cost-strict opt-in.
+
+## Goal
+
+Bring in **independent** external models to critique a project
+artefact. Independent means: the council members never see the host
+agent's reasoning, internal state, or framing language — only the
+artefact (roadmap, diff, prompt, file set) plus a neutral system
+prompt that asks them to think on their own merits.
+
+## Neutrality guidelines (Iron Law)
+
+```
+THE COUNCIL DOES NOT SEE THE HOST AGENT'S ANALYSIS.
+THE COUNCIL DOES NOT SEE PRIOR REPLIES.
+THE COUNCIL SEES THE ARTEFACT + THE NEUTRAL SYSTEM PROMPT. NOTHING ELSE.
+THE HOST AGENT IS THE CONVENER, NEVER A REVIEWER.
+```
+
+If you find yourself wanting to "frame" the artefact for the council,
+stop. Framing is exactly what kills the second-opinion value. Use the
+unbiased system prompts in `scripts/ai_council/prompts.py`; do not
+roll your own.
+
+The host runs the council and synthesises convergence — it is the
+convener, not a reviewer. The reviewer-ban is structural: the host
+wrote (or framed) the artefact and cannot critique it independently.
+Anonymising the host as "Reviewer C" is worse than excluding it — the
+user is told they got an outside vote when they did not. Externals
+down → surface and skip; never substitute the host as a reviewer.
+
+### Neutrality — context-handoff
+
+External reviewers do better critique when they know **what the
+project is**, not just what the artefact looks like. The council
+ships a neutral **handoff preamble** (modelled on `/agent-handoff`)
+in front of every member's system prompt, assembled by
+`prompts.handoff_preamble(project, original_ask)`:
+
+| Carried | Forbidden |
+|---|---|
+| Project name (from `composer.json` / `package.json` / repo dir) | Host-agent identity (Augment, Claude Code, Cursor, Cline, Windsurf, Copilot agent) — stripped line-by-line before send |
+| Stack one-liner inferred from manifest files | Host-agent reasoning, prior turns, internal analysis |
+| One paragraph of repo purpose from `README.md` (max 400 chars) | Host-agent framing language ("I think this looks weak", "the user probably wants…") |
+| The user's **original ask** verbatim (the free-form sentence that triggered `/council`) | Anything the host agent generated about the artefact |
+
+`detect_project_context()` in `scripts/ai_council/project_context.py`
+reads only the manifest files + root README; missing fields collapse
+to `None` and the preamble silently omits the line. With both
+`project=None` and `original_ask=""`, the preamble degrades to the
+bare `NEUTRALITY_PREAMBLE` (v1 shape — back-compat for callers that
+have not migrated yet).
+
+## Execution modes
+
+A council member can run in one of three transports. The neutrality
+preamble is identical across all of them — only the path the bytes
+travel changes.
+
+| Mode | Client | Billable | Transport | Status |
+|---|---|---|---|---|
+| `api` | `AnthropicClient` / `OpenAIClient` / `GeminiClient` / `XAIClient` / `PerplexityClient` | yes | provider SDK + key from `~/.event4u/agent-config/<provider>.key` (legacy `~/.config/agent-config/<provider>.key` read as fallback) | shipped |
+| `manual` | `ManualClient` | no | `stdout` (prompt block) + `stdin` (user pastes the web-UI reply, terminated by a line containing only `END`) | shipped (Phase 2b) |
+| `cli` | `AnthropicCliClient` / `OpenAICliClient` / `GeminiCliClient` | no (subscription-authed) | local subprocess against the vendor CLI (`claude`, `codex`, `gemini`); auth delegated to the CLI's own session, no API key in this process | shipped (anthropic/openai/gemini · Phase 3) |
+
+Resolution lives in `scripts/ai_council/modes.py`:
+`resolve_mode(name, invocation_mode, member_settings, global_mode)`
+with precedence **invocation flag > per-member setting > global
+setting > default (`manual`)**. Whitespace-and-case insensitive; empty
+strings fall through; unknown values raise `InvalidModeError` with
+the offending settings path (`ai_council.mode`,
+`ai_council.members.<name>.mode`, or `/council mode=`).
+
+### Manual-mode UX
+
+`ManualClient` is the user-as-transport variant: the agent prints
+one Markdown block per member (system prompt + handoff preamble +
+artefact between two `═` rules), the user pastes it into a web
+chat (Claude.ai, ChatGPT, Gemini), then pastes the reply back
+ending with a line containing only `END`. After each reply, a 1/2/3
+menu surfaces:
+
+1. More feedback for this member (continue this thread)
+2. Done with this member, move to the next
+3. Abort the council run
+
+`1` re-emits a follow-up block addressed to the **same chat
+thread** (no system prompt repetition). `2` records the round and
+moves to the next member. `3` returns `error="manual_aborted"` for
+that member and the orchestrator stops the fan-out.
+
+### CLI-mode UX
+
+`mode: cli` runs the council through the vendor's local CLI
+instead of the API. Auth is delegated — user logs into each CLI
+once (`claude login`, `codex login`, `gemini`), orchestrator
+inherits the subscription. No API key in this process.
+`billable=False` → cost gate bypassed; the local
+`cli_call_budget.max_calls_per_day.<provider>` quota (state at
+`~/.event4u/agent-config/cli-calls.json`, daily UTC reset) is the
+only per-day brake.
+
+Three vendor CLIs wired:
+
+- **Anthropic / Claude** — invokes `claude --print --output-format json`,
+  parses standard envelope (`result` + `usage` + `session_id` +
+  `total_cost_usd`). Token counts and reported cost survive to
+  `metadata` for audit.
+
+  ```yaml
+  members:
+    anthropic:
+      enabled: true
+      mode: cli
+      model: claude-sonnet-4-5
+  ```
+
+- **OpenAI / Codex** — invokes `codex exec --json`, walks the
+  newline-delimited JSON event stream, pulls text from
+  `item.completed` and tokens from `turn.completed`. Session id
+  preserved.
+
+  ```yaml
+  members:
+    openai:
+      enabled: true
+      mode: cli
+      model: gpt-5
+  ```
+
+- **Google / Gemini** — invokes `gemini --output-format json` with
+  prompt piped on stdin, parses `response` + `stats.models.<m>.tokens`
+  envelope. OAuth consent must be granted once interactively before
+  the CLI is usable from a non-interactive shell.
+
+  ```yaml
+  members:
+    gemini:
+      enabled: true
+      mode: cli
+      model: gemini-2.5-pro
+  ```
+
+Auth-failure stderr from any vendor CLI surfaces as
+`error="auth_expired"` with the original stderr tail in
+`metadata.stderr_tail` so the user knows to re-login. Missing
+binary at construction time fails fast with `CouncilDisabledError`
+naming the binary and the YAML override path — never silently
+substitutes.
+
+`xai` + `perplexity` accept `mode: cli` from Phase 4 onward, but
+their community CLIs DO consume the API key and DO NOT bypass
+per-token billing — contract doc warns explicitly.
+
+### Cost-gate bypass for non-billable members
+
+`ExternalAIClient.billable` is the contract. Clients with
+`billable=False` (`ManualClient`, `AnthropicCliClient`,
+`OpenAICliClient`, `GeminiCliClient`) bypass the cost gate entirely —
+orchestrator skips the projection check, the `on_overrun` callback,
+and the USD-budget short-circuit for that member, but still records
+the response's token counts (from the manual-paste length heuristic
+or the provider's reply, when available) for observability. Mixed
+runs (one cli + one api) gate only the api members.
+
+## Degradation modes
+
+How the council behaves when fewer than two billable members are
+reachable. The orchestrator never silently substitutes — degradation
+is visible to the user.
+
+| Reachable | Behaviour | Independence |
+|---|---|---|
+| **2+** | Full fan-out, multi-round debate. Default. | High — cross-provider diversity. |
+| **1** | Single-voice critique with a degraded-run warning. Multi-round mode lets the model see its own anonymised reply, but convergence ≠ correctness. | Low — shared blind spots. |
+| **0** | Council skipped. Surface the failure, proceed without external review. **Never** substitute the host or an unrequested manual pass. | None. |
+
+Rejected anti-patterns (council convergence, 2026-05-06): persona
+prompts (same model, same blind spots, more cost), temperature
+spread (noise, not signal), host-as-fallback (Iron Law breach).
+Supported single-provider strategy is **sibling models on the same
+provider** (e.g. Sonnet ↔ Opus, gpt-4o ↔ o1) — different training
+cutoffs / reasoning architectures within one provider family. Cost
+is real (siblings price-tier higher); explicit opt-in per invocation,
+not a default.
+
+## Procedure
+
+1. **Resolve target.** Identify the artefact mode (`prompt`, `roadmap`,
+   `diff`, `files`) and locate the source. Refuse to proceed if the
+   target is ambiguous.
+2. **Bundle + redact.** Call `scripts/ai_council/bundler.py` to produce
+   a redacted artefact bundle. If `BundleTooLarge` fires, surface the
+   size and ask the user to narrow scope — do NOT truncate silently.
+3. **Confirm spend.** Before any network call, surface members + cost
+   ceiling and require an explicit user `1` to proceed. Autonomy
+   settings do not override this gate.
+4. **Fan out.** Dispatch the bundle to each enabled council member via
+   `scripts/ai_council/orchestrator.py`. Each member receives the
+   neutrality preamble from `prompts.py` plus the artefact — nothing
+   from the host agent's prior reasoning.
+5. **Render results.** Stack each member's response under its own
+   provider-attributed heading. Never merge or paraphrase responses
+   into the host agent's voice.
+6. **Summarise.** Write a `Convergence / Divergence` block listing
+   agreements, disagreements, and unique insights — provider-attributed.
+7. **Critically evaluate** every finding before it leaves the host
+   (see *Critical evaluation* below). The host is the convener **and**
+   the skeptic — never a reviewer of the artefact itself, but always a
+   reviewer of the **council's output**.
+8. **Translate validated findings to options.** Convert each finding
+   the host accepts (or accepts with modification) into a concrete
+   numbered option for the user. Tag every option with the host's
+   verdict so the user sees the agent's reasoned position, not the
+   council's raw output. The user decides; the council advises; the
+   host filters.
+
+## Critical evaluation — convener-skeptic stance
+
+```
+COUNCIL CONVERGENCE IS NOT CORRECTNESS.
+DO NOT BLINDLY ACCEPT FINDINGS. DO NOT BLINDLY REJECT THEM.
+EVERY FINDING GETS A REASONED VERDICT BEFORE IT REACHES THE USER.
+```
+
+The council is **uninformed about the codebase, ADRs, locked
+contracts, prior decisions, and project history** — it sees only the
+artefact + neutrality preamble. That is the source of its diversity
+**and** its blind spots. Convergence between members can mean shared
+generic best-practice priors, not project-specific correctness.
+
+The host applies a critical lens to **every finding** (convergence
+**and** divergence) before surfacing it as a numbered option:
+
+| Check | Question | Tool |
+|---|---|---|
+| **Codebase fit** | Does the finding match the actual code, files, signatures, conventions? | `view` / `codebase-retrieval` / `grep` |
+| **Locked-decision conflict** | Does it contradict an ADR, kernel rule, contract under `docs/contracts/`, or `docs/decisions/`? | `view` |
+| **Already addressed** | Is it a generic best-practice already covered by an existing rule, skill, or test? | `view` / `grep` |
+| **Cost / benefit** | Is the change worth the diff size, churn, and review cost vs. the marginal benefit? | reasoning |
+| **Hallucination** | Does the finding cite a file, function, or behavior that does not exist? | `view` |
+
+Each finding receives one of three verdicts:
+
+- **`accept`** — codebase fits, no locked-decision conflict, benefit clears cost. Surface as a normal numbered option.
+- **`accept-with-modification`** — core insight valid, but the proposed shape needs adjusting (wrong file, contradicts ADR detail, scope creep). Surface with the **modified** patch and a one-line note.
+- **`reject`** — finding is wrong (hallucinated reference, contradicts a locked decision, already addressed, generic noise). Surface as a **Rejected by host** entry with a one-line reason. Still visible — the user can override.
+
+The verdict is the host's **own** reasoning, not the council's.
+Pretending convergence equals correctness, or paraphrasing council
+output as host analysis, both breach the [`direct-answers`](../../rules/direct-answers.md)
+no-invented-facts rule. When the host cannot reach a confident
+verdict on a finding (mixed evidence, ambiguous scope), it surfaces
+the finding as `needs-input` with the open question — the user
+decides, the host does not guess.
+
+### What this is NOT
+
+- **Not a re-review by the host.** The host did not write the artefact independently and cannot critique it independently — that boundary still holds.
+- **Not a vote against the council.** Rejecting a finding requires evidence (file, line, contract reference), not preference.
+- **Not silent filtering.** Every finding reaches the user with its verdict and reason. The user can pick a `reject` option and override the host.
+
+## Output path convention
+
+Council artefacts (questions, responses, sessions) are **dev-time
+scratch** — gitignored in both the package repo and consumer repos
+and auto-pruned after `ai_council.session_retention_days` (default
+7). They inform a decision; they are not the durable contract. The
+durable contract lives in the roadmap / ADR / skill body that cites
+the council's convergence inline.
+
+**Linking to a specific council file is forbidden by
+[`no-roadmap-references`](../../rules/no-roadmap-references.md)
+(council clause)** — gitignored, not in the cloned repo, gone after
+the retention window. Inline the convergence with date + members
+instead.
+
+Three directories, three modes:
+
+| Mode | Path | Format |
+|---|---|---|
+| **Topic-anchored question** (paired with a roadmap or ADR) | `agents/runtime/council/questions/<topic-slug>.md` | Markdown |
+| **Topic-anchored response** (paired with the question above) | `agents/runtime/council/responses/<topic-slug>.json` | JSON from `council:run --output` |
+| **Ad-hoc session** (no durable artefact yet) | `agents/runtime/council/sessions/<UTC-timestamp>.json` | JSON from `council:run --output` |
+
+`<topic-slug>` is kebab-case and **must match** the corresponding
+roadmap / ADR slug if one exists (e.g. `path-fixes` mirrors the
+matching `road-to-<topic-slug>` roadmap under `agents/roadmaps/`).
+
+### Forbidden
+
+- Files at `agents/` root (e.g. `agents/runtime/council/question-foo.md`).
+- Dot-prefix scratch (e.g. `agents/.council-question-foo.md`).
+- Any other directory below `agents/` (e.g. `agents/scratch/`,
+  `agents/evidence/notes/`). Operator scratch belongs under
+  `agents/runtime/tmp/` (gitignored).
+- Cross-references from any artefact to specific council files —
+  see [`no-roadmap-references`](../../rules/no-roadmap-references.md)
+  (council clause). Inline the convergence summary instead, with
+  date and member list for traceability (`Council (claude-sonnet-4-5
+  + gpt-4o, YYYY-MM-DD) reviewed N candidate strategies; converged
+  on …`).
+
+### Exempt
+
+- `agents/audit-*/` — historical audit bundles. Canonical council
+  dirs are gitignored; audit bundles are tracked, cohesive narratives
+  that may include council artefacts as part of their evidence trail
+  (e.g. `audit-2026-05-14-north-star/` bundles its triggering
+  question, raw responses, and synthesis alongside the audit's
+  findings). The layout linter (`scripts/check_council_layout.py`)
+  skips these directories.
+
+`scripts/check_council_layout.py` is the mechanical check for the
+output path convention — wire it into the package's CI pipeline so
+violations break the build.
+
+## Output format
+
+Every council reply MUST contain, in this order:
+
+1. **Header line** with mode, member count, and total token cost.
+2. **One section per member**, titled `### <provider> · <model>`,
+   containing the member's verbatim output.
+3. **Convergence / Divergence summary** — bullet list, every claim
+   attributed by provider name.
+4. **Host verdict per finding** — one row per finding with `accept`
+   / `accept-with-modification` / `reject` / `needs-input` plus a
+   one-line reason citing host evidence (file:line, ADR, contract).
+   See *Critical evaluation* above.
+5. **User-facing options** — numbered block per `user-interaction`,
+   carrying the host verdict in each option, with "discard council
+   input" always present as an option.
+
+The host agent NEVER ships council output as its own reasoning, and
+NEVER ships the host verdict as council output. Provider attribution
+stays visible in the per-member sections; host verdicts stay
+attributed to the host.
+
+## Synthesis templates (lens-aware)
+
+The **Convergence / Divergence** slot in `council:render` output is
+populated with a lens-specific synthesis prompt. The host agent reads
+this prompt and writes the summary in the shape it dictates. The five
+templates live in `scripts/ai_council/prompts.py::_SYNTHESIS_TABLE`
+and are exposed via `synthesis_template(mode)`.
+
+**R4 Q4 split** — decision lenses get a structured Karpathy-style
+template; creative lenses stay open-ended prose (bare slot):
+
+| Lens | Class | Synthesis sections |
+|---|---|---|
+| `default` | decision | Agreement · Clashes · Blind spots · Recommendation · Next step |
+| `pr` | decision | Consensus · Conflicts · Must-fix before merge · Recommendation |
+| `analysis` | decision | Top-10 by consensus · Supporting · Outliers |
+| `design` | creative | *(no template — open prose passthrough)* |
+| `optimize` | creative | *(no template — open prose passthrough)* |
+
+Input modes (`prompt` / `roadmap` / `diff` / `files`) inherit the
+`default` decision template — they are bundling shapes, not lenses.
+
+**Source citations:**
+* Template shape — Round 2 council verdict
+  (`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-1.md`,
+  Opus's lens-adaptive synthesis proposal).
+* Decision/creative split — Round 4 Q4 verdict
+  (`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-3-responses.json`).
+  R4 reframed `optimize` as creative because perf trade-offs resist
+  pre-templated shape — Performance-wins / Trade-offs /
+  Implementation-order is too rigid for the variety of optimize-lens
+  artefacts. R4 reframed `design` for the same reason — design
+  critiques are inherently narrative.
+
+### `--prose-synthesis` escape hatch (R4 Q4)
+
+Both `council:run` and `council:render` accept symmetric escape-hatch
+flags on top of the lens table:
+
+* `--prose-synthesis` — force creative-lens passthrough (bare slot)
+  regardless of lens. Use when the user on `default`/`pr`/`analysis`
+  prefers a narrative recommendation over the structured template.
+* `--no-prose-synthesis` — force the `default` structured template
+  even on a creative lens. Use when a `design` or `optimize` artefact
+  has a one-shot need for Karpathy-style structure.
+
+The flag is mutually exclusive — picking one disables the other on
+the same invocation. When `council:run` records either flag in the
+output JSON, `council:render` honours it unless the renderer is
+called with an explicit flag of its own.
+
+### Renderer lens resolution
+
+`council:render <responses.json>` resolves the active lens in this
+order: explicit `--prompt-mode` flag > `prompt_mode` field in the
+payload > `mode` field in the payload > `None` (default decision
+template). The `--prose-synthesis` / `--no-prose-synthesis` flag
+overrides the table regardless of how the lens resolved.
+
+## Do NOT
+
+- Do NOT paraphrase council output into the host agent's voice — strip
+  attribution and you've stripped the value.
+- Do NOT surface council findings to the user without a host verdict
+  — convergence ≠ correctness, and the user deserves the agent's
+  reasoned filter, not a raw forward.
+- Do NOT pre-warm the council with the host agent's analysis or
+  identity — that primes the reviewer and collapses diversity.
+- Do NOT silently truncate a too-large bundle — surface the size and
+  ask for narrower scope.
+- Do NOT auto-spend tokens under `personal.autonomy: on` — the cost
+  gate fires every time, no exceptions.
+- Do NOT reuse SDK clients across invocations — re-load keys via
+  `load_*_key()` each call.
+
+## Gotchas
+
+Real failure modes seen in the wild:
+
+- **Bias-by-framing:** agent pastes "I think X is the right answer,
+  what do you think?" → council rubber-stamps. Symptom: 100%
+  convergence, zero unique insight. Fix: send artefact only, neutral
+  preamble, no host reasoning.
+- **Silent budget overrun:** `cost_budget_exceeded` mid-fan-out, agent
+  retries one member to "complete" the council. Result: skewed sample,
+  hidden spend. Fix: surface partial result, stop, ask user.
+- **Identity leak:** roadmap text contains "the agent decided…" —
+  reviewer infers host model and mirrors it. Fix: redact host-agent
+  identity strings before bundling.
+
+| Anti-pattern | Why it's wrong | Correct approach |
+|---|---|---|
+| "Pre-warm" the council with the agent's own analysis. | Bias attack — collapses the reviewer to a yes-man. | Send the artefact text only. |
+| Paste the host-agent identity ("I am Augment / Claude Code…") | Identity primes the reviewer's model. | Neutrality preamble in `prompts.py` already handles this. |
+| Silently truncate a too-large bundle. | Misleads the reviewer into thinking they saw the whole thing. | Bundler raises `BundleTooLarge`; surface and ask for narrower scope. |
+| Reuse the same SDK client across calls without re-loading the key. | Leaks the key in long-lived process state. | Each invocation builds fresh clients from `load_*_key()`. |
+| Auto-spend tokens under `personal.autonomy: on`. | Autonomy ≠ permission to spend money. | Always ask before consultation, even under autonomy. |
+| Forward council convergence to the user as numbered options without a host verdict. | Convergence ≠ correctness; the council never saw the codebase. | Apply the *Critical evaluation* lens; tag every finding `accept` / `accept-with-modification` / `reject` / `needs-input` with one-line reason. |
+| Reject a finding on preference, not evidence. | "I don't like this" is not a verdict. | Cite the file, line, ADR, or contract that justifies the rejection — or surface as `needs-input`. |
+| Paraphrase council output into the host's own analysis to defend a verdict. | Strips attribution, breaches `direct-answers` no-invented-facts. | Verdict cites host evidence (file:line); council output stays attributed in the per-member sections. |
+
+## Redaction expectations
+
+The bundler's redaction pass strips:
+
+- Paths matching `~/.event4u/agent-config/*.key` and the legacy
+  `~/.config/agent-config/*.key`.
+- Lines starting with `Authorization:`.
+- `key = …`, `secret = …`, `token = …`, `password = …` assignments.
+- `sk-ant-…` and `sk-…` token-like strings.
+
+If your artefact contains other sensitive data (customer names,
+internal hostnames, contractual prose) you are responsible for
+scrubbing it before bundling. The redaction pass is a **floor**, not
+a ceiling.
+
+## Cost awareness
+
+Every consultation hits a paid API. The orchestrator enforces
+per-invocation caps from `ai_council.cost_budget`:
+
+- `max_input_tokens` / `max_output_tokens` — token caps across all members.
+- `max_total_usd` — per-invocation USD ceiling. `0` disables the USD ceiling (token caps still apply).
+- `max_calls` — maximum number of council members per invocation.
+- `daily_limit_usd` — rolling 24h spend cap across all `/council`
+  invocations. `0` disables. Persists in
+  `~/.event4u/agent-config/council-spend.jsonl` (mode 0600; legacy
+  `~/.config/agent-config/council-spend.jsonl` read as fallback). Breach
+  fires `on_overrun(event)` with `event.breach_kind == "daily"` and,
+  if the callback returns False or is absent, tags the member
+  `daily_budget_exceeded` instead of `cost_budget_exceeded`.
+
+Prices come from `agents/runtime/.agent-prices.md` (gitignored, refreshed weekly).
+The pricing module bootstraps it from `_default_prices.py` on first
+use and flags it stale when older than the most recent Monday 00:00
+UTC.
+
+### Pre-call estimate format
+
+Before the cost gate, compute `orchestrator.estimate(question, members,
+table)` and render a per-member table. Heuristic: `len(text) / 4` for
+input, member's `max_tokens` ceiling for output (actual spend is
+usually lower).
+
+> External council call — billable
+>
+> Mode: roadmap · Target: `agents/roadmaps/<name>.md` (~3 KB after redaction)
+>
+> | member                          | est. in / out tokens | est. USD |
+> |---------------------------------|---------------------:|---------:|
+> | anthropic / claude-sonnet-4-5   |      ~750 / 1024     |  $0.0176 |
+> | openai / gpt-4o                 |      ~750 / 1024     |  $0.0121 |
+> | **total**                       |                      | **$0.0297** |
+>
+> Budget: 50k in / 20k out tokens · USD ceiling: $0.50
+>
+> 1. Run the consultation
+> 2. Cancel
+
+### Stale price-table gate
+
+If `pricing.is_stale(table)` returns true, ask before proceeding:
+
+> Price table is stale (last_updated: YYYY-MM-DD)
+> 1. Refresh now (`python3 scripts/update_prices.py`)
+> 2. Continue with the stale table
+> 3. Cancel
+
+Do not silently auto-refresh — the user keeps control.
+
+### Mid-flow overrun callback (`on_overrun`)
+
+The orchestrator runs members **sequentially**. Before each member
+whose projected spend would breach a cap, it invokes the
+`on_overrun(event)` callback. The callback returns `True` to proceed
+with that member (raises the effective ceiling for THIS call only)
+or `False` to skip and record `cost_budget_exceeded`. The callback
+fires again for every subsequent breaching member — the user keeps
+control on each step.
+
+> Cost budget overrun — pausing before next member
+>
+> Member: openai / gpt-4o (member 2 of 2)
+> Already spent: ~620 in / ~480 out tokens · $0.0094
+> Next call estimate: ~750 in / 1024 out tokens · $0.0121
+> **Projected total after this call: $0.0215** (ceiling: $0.0150)
+>
+> 1. Continue with this member
+> 2. Skip this member (records `cost_budget_exceeded`, continues with the rest)
+
+Without `on_overrun`, breaching short-circuits all remaining members
+(v1 fallback). Do not retry silently. Surface the partial result and
+ask the user.
+
+## Multi-round debate (`rounds:N`)
+
+`consult(..., rounds=N)` enables 2-3 round critique loops. Round 1
+runs the standard single-round flow. Round 2+ rebuilds the user
+prompt as `<original artefact> + <prior round, anonymised>` so each
+member can refine, agree, or push back on the previous critique
+without seeing which provider produced which point.
+
+The default round count comes from `defaults.min_rounds` in
+`~/.event4u/agent-config/settings/.ai-council.yml` (default `2` so members critique each other
+at least once before convergence). The host agent does **not** ask
+"how many rounds?" when the requested count is `<= min_rounds` —
+the settings owner already made that decision. Ask only when a
+genuinely complex artefact justifies more depth than the default.
+
+### Deep-reasoning tier (`council_depth: deep`)
+
+Architecture review, refactoring proposals, and bug-diagnosis runs
+benefit from an extra critique round. The deep tier is opt-in per
+artefact:
+
+1. The consuming **rule, skill, or command** declares
+   `council_depth: deep` in its frontmatter. The schema accepts
+   **only `deep`** — `standard` is the implicit default and is
+   rejected by the linter (every frontmatter byte costs context
+   window; see `scripts/schemas/{rule,skill,command}.schema.json`).
+   To return an artefact to default depth, **delete the key**.
+2. The **host agent** reads that frontmatter when it dispatches the
+   council and passes `--depth deep` to `council_cli`. If multiple
+   active artefacts disagree, **deep wins** (max policy).
+3. The **CLI** floors the round count at
+   `max(ai_council.deep_min_rounds, ai_council.min_rounds)` —
+   defaults to `3` and `2` respectively. Lowering `deep_min_rounds`
+   below `min_rounds` has no effect (defensive max).
+
+The CLI itself has no knowledge of frontmatter; the contract is the
+flag. Resolution chain (highest priority first):
+
+```
+--rounds N           → explicit, any value (user override)
+--depth deep         → max(deep_min_rounds, min_rounds)
+(no flag)            → min_rounds (default 2)
+```
+
+| Property | Behaviour |
+|---|---|
+| Default count | `ai_council.min_rounds` (default `2`). Override per-invocation with `rounds:N` (or `--rounds N` to the CLI). |
+| Deep floor | `ai_council.deep_min_rounds` (default `3`). Activated by `council_depth: deep` in artefact frontmatter (host translates to `--depth deep`) or explicit `--depth deep` on the CLI. Floored at `min_rounds`. |
+| Anonymisation | Provider/model identity is stripped. Reviewers are labelled `Reviewer A / B / C…` in input order. |
+| Errored prior responses | Skipped — they reveal nothing useful and can leak provider error formats. |
+| Cost budget | Accumulates across rounds. A round-2 call that breaches the cap fires `on_overrun` exactly like a round-1 breach. |
+| Daily limit | Same — every billable round-2 call records spend in the rolling 24h ledger. |
+| Return value | Final round only. Use `on_round_complete(round_idx, responses)` to capture intermediate rounds for rendering. |
+
+> Iron Law: anonymisation is non-negotiable. If you ever need to
+> surface "which model said what" between rounds, that is a different
+> feature — debug-only, off by default, never enabled in user-facing
+> output. The neutrality contract dies the moment a member learns it
+> is talking to Claude vs GPT in round 2.
+
+Pre-call estimate must surface the round count: total = `N × single-round cost`. Render inline:
+
+```
+External council call — billable · 2 rounds
+Round 1: artefact only
+Round 2: artefact + anonymised round 1 critiques
+
+| member             | per-round | × 2     |
+|--------------------|----------:|--------:|
+| anthropic/sonnet   |   $0.0176 | $0.0352 |
+| openai/gpt-4o      |   $0.0121 | $0.0242 |
+| **total**          |           | $0.0594 |
+```
+
+### Manual-mode parity
+
+The orchestrator drives rounds the same way for `api` and `manual`
+transports. One round = one full pass over every enabled member,
+top-to-bottom, then `_augment_for_next_round()` folds the
+anonymised critiques into the round-N+1 user prompt. For manual
+mode this means: emit the round-1 block for member A → user
+pastes A's reply → next member B → user pastes B's reply → host
+agent consolidates round 1 → emit the round-2 block (now carrying
+the anonymised round-1 critiques) for member A → … and so on
+until the configured round count is reached. ManualClient's
+internal "more feedback" follow-up loop (1 / 2 / 3 menu) is
+**inside** a single member's chat thread and is orthogonal to the
+orchestrator-level rounds.
+
+### `/council debate` sub-command (progressive disclosure)
+
+`/council debate <artefact> [--rounds N] [--continue-as-debate <session>]`
+runs an **interactive** multi-round critique with a confirmation gate
+between every round so the user can stop the spend at any point.
+
+| Property | Behaviour |
+|---|---|
+| Round flow | Same orchestrator as `rounds:N` (`run_debate()`), but each round prints its responses then pauses on a y/n prompt before launching the next round. |
+| Cost gate | After every round the CLI prints `Spent so far: $X · Next round: ~$Y · Cap: $Z`. `n` exits cleanly with partial results; `y` continues. |
+| Hard cap | If the projected next-round cost would breach `max_total_usd`, `run_debate()` raises `DebateCapExceeded` and the CLI exits with the partial transcript. No silent overrun. |
+| `--continue-as-debate` | Seeds round 1 from an existing `/council default` (or analysis lens) session. No round-1 API calls are billed; round 2+ run normally. Member list must match. |
+| Session files | One file per round under `agents/runtime/council/sessions/<slug>/debate-round-NN.md`. |
+| Anonymisation | Identical to `rounds:N`. The continue-as-debate path also anonymises the seeded round-1 responses when building the round-2 prompt. |
+
+Use this when the artefact is genuinely contentious and the user
+wants to control depth interactively. For a fire-and-forget
+multi-round run, prefer `consult(..., rounds=N)` or `--rounds N` on
+`/council default`.
+
+
+## Karpathy peer-review (opt-in)
+
+After the final deliberation round, an optional **anonymous peer-review
+pass** lets each member critique the *other* members' responses for
+blind spots before synthesis. Inspired by Andrej Karpathy's "ask the
+strongest models to review each other anonymously" pattern; see his
+[talks / threads on inter-model critique](https://karpathy.ai/) and the
+internal verdict in
+`agents/runtime/council/sessions/2026-05-14-ai-council-redesign/round-2.md`
+(R2 split: one approve-as-flag, one reject-as-default → opt-in only).
+
+Pipeline order when every feature is active:
+
+```
+deliberation rounds → peer-review → consensus-scoring → synthesis
+```
+
+Activation — two equivalent paths:
+
+* CLI: `--peer-review` on `council:estimate` or `council:run`.
+* Config: `ai_council.peer_review.enabled: true` in
+  `~/.event4u/agent-config/settings/.ai-council.yml`. Default is `false`.
+
+Mechanics:
+
+1. The final deliberation round's outputs are anonymised into
+   `Response-A`, `Response-B`, … in stable input order. Provider /
+   model identity is stripped (Iron-Law neutrality holds); empty or
+   errored deliberation responses are skipped.
+2. Each member receives an N−1 view (its own response filtered out)
+   plus the Karpathy prompt: *strongest response*, *weakest blind
+   spot*, *what did everyone miss*, *refinement*.
+3. The N critiques flow back into synthesis through a
+   "Peer-Review-Surfaced Blind Spots" addendum on the lens template.
+4. **Advisor preserve-persona (R4 Q3, hard-coded):** when the
+   deliberation was an advisor-mode run (Phase 6), anonymisation
+   strips provider identity but **preserves the advisor persona
+   label**. Peer-review renders as `Response A (Contrarian)`, never
+   `Response A (Anthropic Opus)`. Plain-member runs strip identity
+   entirely.
+
+Cost — adds exactly N billable calls (one per member) at the same
+per-call cost as a deliberation call. The `council:estimate` table
+surfaces the delta as a `+peer-review: +N calls (~+$X)` row.
+
+Needs ≥ 2 distinct deliberation outputs; below that the round is a
+no-op and nothing extra is billed. Self-review is structurally
+impossible — a member never sees its own response.
+
+## Thinking-style advisors (replace-mode)
+
+Phase 6 introduces five **advisor personas** the council adopts in
+*replace-mode*: an enabled advisor substitutes its bound member's
+plain call with the same provider running the advisor's persona
+prompt. Total call count stays the same — only the system prompt
+swaps.
+
+| Advisor | Default bound member | Focus |
+|---|---|---|
+| **Contrarian** | `anthropic` | strongest counterargument, hidden assumptions |
+| **First-Principles** | `anthropic` | strip metaphor, derive from physics / math / cost |
+| **Expansionist** | `openai` | adjacent opportunities, second-order effects |
+| **Outsider** | `openai` | naive-but-sharp questions, beginner's-mind probes |
+| **Executor** | `anthropic` | what ships this quarter, what blocks delivery |
+
+Activation — edit `~/.event4u/agent-config/settings/.ai-council.yml` and flip the advisor's
+`enabled: true`. Optional `model: <name>` overrides the bound
+member's default model. An advisor referencing a disabled member
+fails closed at config load — never silently skipped.
+
+```yaml
+advisors:
+  contrarian:
+    enabled: true        # ← swap anthropic's plain call for contrarian
+    member: anthropic
+    # model: claude-opus-4   # optional pin
+```
+
+`council:estimate` surfaces every active swap on a dedicated line
+above the cost table:
+
+```
+council:estimate · mode=prompt · members=2 (billable=2)
+  advisor: Contrarian on anthropic via claude-sonnet-4-5
+anthropic/claude-sonnet-4-5: ~991 in + 256 out  =  $0.0068
+openai/gpt-4o: ~208 in + 256 out  =  $0.0031
+```
+
+Cost-bounded — replace-mode never adds calls. The persona prompt is
+larger than plain (~1k extra input tokens per swap); output tokens
+and call count are unaffected. Peer-review preserves the advisor
+label while stripping provider identity (`Response A (Contrarian)`).
+Two enabled advisors on the same member is a config error.
+
+## Decision-replay artefact (Phase 9, audit trail)
+
+Every session that runs consensus scoring drops a `decision-replay.md`
+next to `responses.json`. Pure projection of consensus + final-round
+member texts — **no extra model calls, no extra spend**. Surfaces per
+top finding: verdict band (Strong/Moderate/Weak), evidence-quality
+(H/M/L), agree/dissent split, one key argument per member.
+
+Two render modes — **Full** (per-member arguments attributed to
+`provider:model`) and **Redacted** (verdict + evidence-quality + counts
+only). Toggles: `ai_council.decision_replay.{enabled,
+include_member_arguments}` global; `ai_council.lenses.<lens>.decision_replay.*`
+per-lens override.
+
+CLI — written automatically by `council run` on lenses that score
+consensus. `council replay <responses.json>` re-renders from a saved
+session; `--redact-member-arguments` / `--include-member-arguments`
+flip the view independent of config (share redacted variant of an
+already-paid run).
+
+## Lightweight-QA fast-path (Phase 11)
+
+Low-impact questions from Phase 10's impact router → restricted fast-path
+in place of full debate. Trade-off explicit: **1 round · ≤2 members ·
+$0.05/answer · 2500 tokens**. No advisors, no peer-review, no consensus
+scoring — quick answer + transparency marker, not deliberation.
+
+### Iron Law
+
+`high_impact` and `user_required` **never** route to fast-path,
+regardless of config. Schema validation rejects override. Fast-path
+activates only when:
+
+1. `ai_council.enabled: true` AND
+2. `decision_resolution.low_impact.mode: council` AND
+3. ≥1 member has `participate_low_impact: true` (default `false` —
+   explicit opt-in per member).
+
+Default `low_impact` route = **`agent`** — nothing reaches council
+without explicit two-knob opt-in (flip class → `council` *and* mark
+≥1 member `participate_low_impact: true`). Worked YAML, validation,
+unavailable-marker contract → [`ai-council-config § Low-impact council opt-in`](../../../docs/contracts/ai-council-config.md#low-impact-council-opt-in).
+
+### Output marker (always surfaced)
+
+* **Resolved** — `> Resolved via low-impact council (anthropic): <answer>`
+* **Split** — `> Low-impact council split — escalating to user (anthropic: X / openai: Y):`
+* **Aborted** — `> Low-impact council aborted (token cap) — escalating to user:`
+
+Marker mandatory — agent never silently substitutes fast-path verdict
+for its own answer.
+
+### Session artefact
+
+Every fast-path attempt appends one line to
+`agents/runtime/council/sessions/<date>-<slug>/low-impact-resolutions.md`:
+
+```
+2025-05-14T10:00:00Z | resolved | members=2/2 | members(anthropic, openai) cost=$0.0034 | Q=Service vs Repository for this read path?
+```
+
+Append-only, one line per resolution. Parser tolerates free-form
+headers around canonical lines.
+
+### `council replay --low-impact-stats`
+
+Re-projection of session log → summary block:
+
+```
+$ council replay agents/runtime/council/sessions/2025-05-14-foo/responses.json --low-impact-stats
+# Low-impact fast-path · session summary
+
+- attempts: 4
+- status: aborted=1 · resolved=2 · split=1
+- members: anthropic=4 · openai=3
+- total cost: $0.0096
+```
+
+No model calls — pure markdown parse. Returns 0 when session has no
+fast-path entries (clean session is not an error).
+
+## See also
+
+- `/council` command — the user-facing entry point.
+- `subagent-orchestration` skill — internal multi-agent variant (no
+  network, no spend, but no diversity of weights either).
+- `scripts/ai_council/prompts.py` — neutrality preamble + per-mode
+  system prompts.
+- `scripts/ai_council/advisors.py` — replace-mode planning + persona
+  resolution.
+- `scripts/ai_council/bundler.py` — redaction pattern set + size
+  guard.
+- `docs/customization.md` § `ai_council.*` — settings reference.
+- `docs/contracts/ai-council-config.md` § advisors — schema + precedence
+  contract.
+- `docs/contracts/ai-council-config.md` § Decision-replay artefact —
+  Phase 9 audit trail contract + redaction modes.
+- `scripts/ai_council/replay.py` — pure projection renderer (no model
+  calls).