@event4u/agent-config 2.11.0 → 2.13.0

package/.agent-src/commands/council/analysis.md

@@ -0,0 +1,142 @@
+---
+name: council:analysis
+tier: 2
+cluster: council
+sub: analysis
+skills: [ai-council]
+description: Run the council on a local analysis output (project-analyze, audit script, codebase scan) — critiques the analysis itself for dedup, evidence quality, and roadmap-readiness.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "council on this analysis, critique the project-analyze output, second opinion on the audit findings, turn analysis into roadmap"
+  trigger_context: "user has a local analysis artefact (agents/analysis/*.md|json) and wants an external critique of the analysis quality + roadmap-ready follow-ups"
+---
+
+# /council analysis
+
+## Instructions
+
+Specialised council mode for **local analysis artefacts** — `/project-analyze`
+output, audit reports, codebase scans under `agents/analysis/`. Wraps
+`/council default files:<path>` with the `analysis` neutrality preamble that
+focuses members on **critiquing the analysis itself** (dedup, evidence
+quality, roadmap-readiness) rather than re-reviewing the underlying code.
+
+The synthesis output is shaped for direct consumption by
+`/roadmap-create` — Top-N consensus findings + per-finding metadata
+(`evidence-grade`, `roadmap-ready`, `supporting-citation`).
+
+### 1. Resolve the analysis artefact
+
+The user invoked `/council analysis <path>` or `/council analysis`. If
+no path was supplied, ask (one question per turn, per
+`ask-when-uncertain`):
+
+> Which analysis artefact should the council review?
+>
+> 1. A file path under `agents/analysis/` (`.md` or `.json`)
+> 2. Multiple files (one analysis split across sections)
+> 3. Free-form analysis text in the chat — paste it now
+
+Pick **1** or **2** → use `files:` mode of `/council default`.
+Pick **3** → use `prompt:` mode of `/council default`.
+
+### 2. Capture the upstream-analysis goal
+
+Look for the artefact's stated goal — the first paragraph after the
+title, a `## Goal` / `## Scope` section, or the analyzer command that
+produced it (often in the file header). That goal is the `original_ask`
+for the handoff preamble. If absent, ask the user (one question per
+turn):
+
+> What was the goal of this analysis? (one sentence — used as neutral
+> framing for the council, not their critique)
+
+A follow-up question MAY also be supplied as part of the invocation
+(e.g. `/council analysis <path> "which findings warrant a roadmap?"`).
+Append it to `original_ask` so members see both the analyzer goal and
+the consumer question.
+
+### 3. Run /council default with the analysis mode preamble
+
+Invoke the matching `/council default` form:
+
+- `files:` → `/council default files:<paths>` with `--prompt-mode analysis`.
+- `prompt:` → `/council default prompt:"<artefact text>"` with
+  `--prompt-mode analysis`.
+
+`--prompt-mode` is the CLI flag (`scripts/council_cli.py`) that
+swaps the lens addendum after the bundler has run. The bundle shape
+stays as the resolved `--input-mode` (prompt | roadmap | files).
+
+The `analysis` mode addendum from `scripts/ai_council/prompts.py`
+focuses council members on:
+
+- Deduplicating findings restated under different headings.
+- Scoring evidence quality (confirmed / inferred / speculative).
+- Separating roadmap-ready findings from ones that need a discovery
+  loop first.
+- Proposing 3–5 ranked follow-up actions with supporting citations.
+
+The cost gate from `/council default` Step 3 still applies. Render via
+Step 5/5a/5b of `/council default`.
+
+### 4. Render the report (analysis-shaped header + Top-N consensus)
+
+Use the standard stacked + Convergence/Divergence layout. Add a
+one-line analysis header at the top so reviewers know the lens:
+
+```
+## Council on <artefact path> — analysis lens
+```
+
+After the standard Convergence / Divergence blocks, append a
+**Top-N consensus** block in the shape consumed by `/roadmap-create`:
+
+```
+## Top-N consensus findings (roadmap-ready first)
+
+1. <finding title>
+   - evidence-grade: confirmed | inferred | speculative
+   - roadmap-ready: yes | needs-discovery
+   - cited by: <member names — anonymised post-render is fine>
+   - supporting citation: <file:line | section heading from the upstream analysis>
+
+2. ...
+```
+
+Order: roadmap-ready findings first, ranked by member-consensus count;
+then `needs-discovery` items. Cap at N=10 unless the upstream analysis
+has fewer findings.
+
+### 5. Hand back to the user
+
+The council is **advisory**. Do **not** rewrite the analysis or open
+roadmap files based on findings. Surface the Top-N block and offer:
+
+> 1. Feed the Top-N block into `/roadmap create` to draft a roadmap.
+> 2. Discard — keep findings in chat only.
+> 3. Re-run with a narrower scope.
+
+### Hard floor (restated)
+
+`/council analysis` produces **text only**. It does NOT edit the
+analysis file, write roadmap files, or modify the codebase. Roadmap
+authoring is the explicit downstream step, not a side-effect.
+
+## Failure modes
+
+- **No artefact resolvable** → ask once; if still empty, stop.
+- **Artefact too large** → bundler raises `BundleTooLarge`; suggest
+  splitting (`/council default files:<single-section>` per heading).
+- **Analysis has zero citations** → flag in the rendered report; every
+  finding will score as `speculative`. The council will say so loudly
+  and the Top-N block will be empty of `confirmed` rows — that is the
+  signal to re-run the upstream analyzer with stricter evidence rules.
+
+## See also
+
+- `/council default` — base orchestration entry point.
+- `/project-analyze` — primary upstream producer of analysis artefacts.
+- `/roadmap create` — primary downstream consumer of the Top-N block.
+- `ai-council` skill — neutrality guidelines.

package/.agent-src/commands/council/debate.md

@@ -0,0 +1,129 @@
+---
+name: council:debate
+tier: 2
+cluster: council
+sub: debate
+skills: [ai-council]
+description: Multi-round council debate with progressive cost disclosure — each member produces a position, then rebuts the strongest opposing position in subsequent rounds. User confirms spend between rounds.
+disable-model-invocation: true
+suggestion:
+  eligible: true
+  trigger_description: "council debate on X, multi-round rebuttal, escalate council to debate mode, push the council to argue not synthesize"
+  trigger_context: "user wants real pushback — initial positions plus explicit rebuttals across rounds, with progressive cost confirmation between rounds"
+---
+
+# /council debate
+
+## Instructions
+
+Specialised council mode for **multi-round debates**. Each enabled member
+produces an initial position in Round 1, then rebuts the strongest
+opposing position in subsequent rounds. The orchestrator pauses between
+rounds and asks the user to continue (progressive cost disclosure). Hard
+cap: `ai_council.cost_budget.max_total_usd` aborts the next round if
+the projection breaches the cap, persisting the partial debate.
+
+This is **not a flag** on `/council default` — debate mode changes the
+orchestration shape (N members × R rounds = N×R calls) and the cost UX,
+so it earns its own sub-command per the R4 verdict.
+
+### 1. Resolve the topic
+
+The user invoked `/council debate "<topic>"` or `/council debate <path-to-artefact>`.
+Treat the argument as the **topic** of the debate (a question, a
+proposal, an architectural call). If missing, ask (one question per
+turn, per `ask-when-uncertain`):
+
+> What is the topic of the debate?
+>
+> 1. Inline topic (e.g. "Should we adopt event sourcing for the orders module?")
+> 2. Path to a file containing the topic / artefact
+> 3. Cancel
+
+Capture the resolved topic as `original_ask` verbatim. Do **not** add
+the agent's framing.
+
+### 2. Decide round count + auto-continue
+
+Default: 2 rounds (initial position + one rebuttal). Cap: the value of
+`defaults.debate_max_rounds` in [`agents/.ai-council.yml`](../../../agents/.ai-council.yml)
+(default 4). `--rounds N` overrides the default; values above the cap
+are rejected by the CLI.
+
+Auto-continue is **off by default** — the user explicitly opts in via
+`--auto-continue` when they want to skip the y/N gate between rounds.
+The hard cost cap still applies regardless.
+
+### 3. Estimate (always)
+
+Run `council:estimate` first using `--prompt-mode=debate` (the CLI sets
+this automatically when invoked via `debate`). The estimate covers
+**one round**. Multiply by the planned round count for the worst-case
+projection. Surface the projection to the user with a clear note that
+progressive disclosure may stop the debate early.
+
+### 4. Cost confirmation (ALWAYS ASK)
+
+Per [`ai-council` skill § cost gate](../../skills/ai-council/SKILL.md),
+always surface the projected total spend and ask for explicit consent
+before invoking. Numbered options:
+
+> The debate is projected to cost **$X.XXXX** ($Y.YYYY × N rounds, worst case).
+>
+> 1. Run all N rounds (auto-continue, no between-round prompt)
+> 2. Run round-by-round (confirm before each next round) — recommended
+> 3. Cancel
+
+The default recommendation is option 2 (progressive disclosure). Map
+option 1 to `--auto-continue`, option 2 to interactive mode, option 3
+to abort.
+
+### 5. Invoke the CLI
+
+```bash
+python3 scripts/council_cli.py debate <topic-path> \
+  --output agents/council-sessions/<date>-<slug>/ \
+  --confirm \
+  --rounds <N> \
+  [--auto-continue] \
+  [--continue-as-debate <prior-session.json>] \
+  --original-ask "<verbatim topic>"
+```
+
+Session directory shape: `agents/council-sessions/<YYYY-MM-DD>-debate-<slug>/`
+with `debate-round-1.json`, `debate-round-2.json`, … written incrementally.
+An interrupted debate leaves every completed round on disk.
+
+### 6. Continuation pivot (optional)
+
+If the user has a prior `/council default` session and wants more
+pushback, they can pivot via `--continue-as-debate <session.json>`. The
+orchestrator seeds Round 1 from the existing responses (no calls billed
+for Round 1) and starts the rebuttal loop at Round 2. **Members + models
+must match** the source session — a mismatch is a hard error.
+
+### 7. Render the final synthesis
+
+After all rounds complete, render the last round's JSON via
+`/council` render flow:
+
+```bash
+python3 scripts/council_cli.py render agents/council-sessions/<dir>/debate-round-<N>.json
+```
+
+The debate mode uses the structured decision-lens template (Karpathy
+synthesis) by default. `--prose-synthesis` switches to open-ended prose.
+
+### 8. Hard floor — text only
+
+`/council debate` produces text artefacts (round JSONs + synthesis
+markdown). It does NOT edit files, commit, push, or open PRs. The
+session directory is the canonical audit trail.
+
+## Cap exceeded
+
+If `DebateCapExceeded` fires, the CLI exits with code 3 and the partial
+debate is persisted. Surface the partial-debate path to the user and
+ask whether to (a) raise the cap in `agents/.ai-council.yml` and rerun,
+(b) stop here and render the partial result, or (c) start a new debate
+with a smaller scope.

package/.agent-src/commands/council/default.md

@@ -126,9 +126,16 @@ redaction, and prints the per-member preview without spending:
     [--input-mode prompt|roadmap] \
     [--max-tokens N] \
     [--mode-override api|manual] \
+    [--prompt-mode pr|design|optimize|analysis] \
     [--original-ask "<framing sentence>"]
 ```
 
+`--prompt-mode` is the lens-override flag routed by the
+`/council pr|design|optimize|analysis` wrappers. It swaps the
+per-mode neutrality addendum (see `scripts/ai_council/prompts.py`
+`_MODE_TABLE`) without changing the bundle shape. Bare
+`/council default` invocations leave it unset.
+
 For `prompt:"<text>"` mode, write the text to a temp file first
 (`mktemp` is fine) and pass that path. For `roadmap:<path>`, pass the
 roadmap file with `--input-mode roadmap`. `diff` and `files` modes
@@ -155,6 +162,7 @@ Once the user picks `1`, invoke the same arguments with `run` plus
     [--rounds 1|2|3] \
     [--depth standard|deep] \
     [--input-mode …] [--max-tokens …] [--mode-override …] \
+    [--prompt-mode …] \
     [--original-ask "<framing sentence>"]
 ```
 

package/.agent-src/commands/council/design.md

@@ -17,8 +17,8 @@ suggestion:
 ## Instructions
 
 Specialised council mode for **design documents, ADRs, and
-architecture proposals**. Wraps `/council files:<paths>` (or
-`/council prompt:"…"`) with the `design` mode neutrality preamble that
+architecture proposals**. Wraps `/council default files:<paths>` (or
+`/council default prompt:"…"`) with the `design` mode neutrality preamble that
 focuses members on architectural risk rather than line-level
 correctness.
 
@@ -33,8 +33,8 @@ path was supplied, ask (one question per turn):
 > 2. Multiple files / a directory (the bundler will gather them)
 > 3. A free-form proposal in the chat — paste it now
 
-Pick **1** or **2** → use `files:` mode of `/council`.
-Pick **3** → use `prompt:` mode of `/council`.
+Pick **1** or **2** → use `files:` mode of `/council default`.
+Pick **3** → use `prompt:` mode of `/council default`.
 
 ### 2. Capture the originating ask
 
@@ -46,13 +46,16 @@ goal section, ask the user (one question per turn):
 > What is the goal of this design? (one sentence — used as neutral
 > framing for the council, not their analysis)
 
-### 3. Run /council with the design mode preamble
+### 3. Run /council default with the design mode preamble
 
-Invoke the matching `/council` form:
+Invoke the matching `/council default` form:
 
-- `files:` → `/council files:<paths>` with `mode_override=design`.
-- `prompt:` → `/council prompt:"<artefact text>"` with
-  `mode_override=design`.
+- `files:` → `/council default files:<paths>` with `--prompt-mode design`.
+- `prompt:` → `/council default prompt:"<artefact text>"` with
+  `--prompt-mode design`.
+
+`--prompt-mode` is the CLI flag (`scripts/council_cli.py`) that
+swaps the lens addendum after the bundler has run.
 
 The `design` mode addendum from `scripts/ai_council/prompts.py`
 focuses council members on:
@@ -62,7 +65,8 @@ focuses council members on:
 - Sequencing risk (does step N really not block step N+1?).
 - Open questions disguised as decisions.
 
-The cost gate from `/council` Step 3 still applies.
+The cost gate from `/council default` Step 3 still applies. Render via
+Step 5/5a/5b of `/council default`.
 
 ### 4. Render the report
 
@@ -88,11 +92,11 @@ design file, open ADR PRs, or modify the codebase.
 
 - **No artefact resolvable** → ask once; if still empty, stop.
 - **Artefact too large** → bundler raises `BundleTooLarge`; suggest
-  splitting (`/council files:<single-file>` per section).
+  splitting (`/council default files:<single-file>` per section).
 
 ## See also
 
-- `/council` — base orchestration entry point.
+- `/council default` — base orchestration entry point.
 - `/feature plan` / `/feature refactor` — where design changes get
   written, after the council surfaces issues.
 - `ai-council` skill — neutrality guidelines.

package/.agent-src/commands/council/optimize.md

@@ -20,7 +20,7 @@ Specialised council mode for **optimization targets**: hot paths,
 slow queries, allocation profiles, or the output of an `/optimize-*`
 command (`/optimize-skills`, `/optimize-agents`,
 `/optimize-augmentignore`, `/optimize-rtk-filters`). Wraps
-`/council` with the `optimize` neutrality preamble, which focuses
+`/council default` with the `optimize` neutrality preamble, which focuses
 members on **ranked**, **evidence-based** suggestions instead of
 generic "you should profile" advice.
 
@@ -37,19 +37,19 @@ If nothing was supplied, ask (one question per turn):
 >    the report to the council
 > 4. A free-form description of the bottleneck
 
-Pick **1** → `/council files:<paths>` with `mode_override=optimize`.
-Pick **2** → `/council prompt:"<query + context>"` with
-`mode_override=optimize`.
+Pick **1** → `/council default files:<paths>` with `--prompt-mode optimize`.
+Pick **2** → `/council default prompt:"<query + context>"` with
+`--prompt-mode optimize`.
 Pick **3** → run the chosen `/optimize-*` command first, then feed
-its report file to `/council files:<report>` with
-`mode_override=optimize`.
-Pick **4** → `/council prompt:"<description>"` with
-`mode_override=optimize`.
+its report file to `/council default files:<report>` with
+`--prompt-mode optimize`.
+Pick **4** → `/council default prompt:"<description>"` with
+`--prompt-mode optimize`.
 
 ### 2. Capture the constraint
 
 Optimization is meaningless without a target metric. Ask **once**
-(one question per turn) before invoking `/council`:
+(one question per turn) before invoking `/council default`:
 
 > What does "better" mean here?
 >
@@ -63,10 +63,10 @@ Optimization is meaningless without a target metric. Ask **once**
 The chosen metric becomes the `original_ask` for the handoff preamble:
 `Optimize for <metric>: <one-line scope>`.
 
-### 3. Run /council with the optimize mode preamble
+### 3. Run /council default with the optimize mode preamble
 
-Invoke the matching `/council` form (`files:` / `prompt:`) with
-`mode_override=optimize`. The `optimize` mode addendum from
+Invoke the matching `/council default` form (`files:` / `prompt:`) with
+`--prompt-mode optimize`. The `optimize` mode addendum from
 `scripts/ai_council/prompts.py` requires members to:
 
 - Rank suggestions by expected impact on the chosen metric, not by
@@ -78,7 +78,8 @@ Invoke the matching `/council` form (`files:` / `prompt:`) with
 - Mark at least one suggestion that requires measurement before
   committing — i.e. flag what is hypothesis vs. confirmed.
 
-The cost gate from `/council` Step 3 still applies.
+The cost gate from `/council default` Step 3 still applies. Render via
+Step 5/5a/5b of `/council default`.
 
 ### 4. Render the report
 
@@ -106,11 +107,11 @@ run benchmarks, or change configuration.
   unit, ask once for clarification; if still vague, stop. Generic
   "make it better" is exactly what this command refuses to enable.
 - **Target too large** → bundler raises `BundleTooLarge`; suggest
-  narrowing to the hot path (`/council files:<single-file>`).
+  narrowing to the hot path (`/council default files:<single-file>`).
 
 ## See also
 
-- `/council` — base orchestration entry point.
+- `/council default` — base orchestration entry point.
 - `/optimize-skills`, `/optimize-agents`, `/optimize-augmentignore`,
   `/optimize-rtk-filters` — internal optimization commands; their
   output can be fed to `/council optimize` for an external ranking.

package/.agent-src/commands/council/pr.md

@@ -16,7 +16,7 @@ suggestion:
 
 ## Instructions
 
-Specialised council mode for **GitHub PRs**. Wraps `/council diff:<base>..<head>`
+Specialised council mode for **GitHub PRs**. Wraps `/council default diff:<base>..<head>`
 with a PR-aware neutrality preamble (the `pr` mode) and an opt-in
 "post a comment summary on the PR" step at the end.
 
@@ -55,26 +55,26 @@ git fetch origin <head>:<head>
 Compute the diff range as `origin/<base>..origin/<head>` (or the local
 refs if already fetched).
 
-### 4. Run /council with the pr mode preamble
+### 4. Run /council default with the pr mode preamble
 
-Invoke `/council diff:<base>..<head>` with:
+Invoke `/council default diff:<base>..<head>` with:
 
 - `original_ask` = PR title + body (capped per
   `bundler.size_guard`; warn if truncated).
-- The neutrality preamble uses the `pr` mode addendum from
-  `scripts/ai_council/prompts.py` — focuses members on
-  PR-specific risks (shipping risk, reviewer fatigue, scope creep)
-  on top of the generic diff focus (correctness, security, tests,
-  maintainability).
+- Pass `--prompt-mode pr` so the neutrality preamble uses the `pr`
+  mode addendum from `scripts/ai_council/prompts.py` — focuses
+  members on PR-specific risks (shipping risk, reviewer fatigue,
+  scope creep) on top of the generic diff focus (correctness,
+  security, tests, maintainability).
 
-The cost gate from `/council` Step 3 still applies. Council is
+The cost gate from `/council default` Step 3 still applies. Council is
 billable; suppress the question only when the resolved members are
 all-manual.
 
 ### 5. Render the report
 
 Use the standard stacked + Convergence/Divergence layout from
-`/council` Step 6. Add a one-line PR header at the top:
+`/council default` Step 5/5a/5b. Add a one-line PR header at the top:
 
 ```
 ## Council on PR #<number> — <title>
@@ -116,10 +116,10 @@ comment**. It does **NOT**:
 - **PR is closed / merged** → ask whether to proceed (council on a
   closed PR is fine for retrospectives) or cancel.
 - **Diff too large** → bundler raises `BundleTooLarge`; suggest
-  `/council files:<paths>` for a narrower review.
+  `/council default files:<paths>` for a narrower review.
 
 ## See also
 
-- `/council` — base orchestration entry point.
+- `/council default` — base orchestration entry point.
 - `ai-council` skill — neutrality guidelines.
 - `/review-changes` — internal four-judge variant for local diffs.

package/.agent-src/commands/council.md

@@ -1,7 +1,7 @@
 ---
 name: council
 tier: 1
-description: Council orchestrator — routes to default, pr, design, optimize
+description: Council orchestrator — routes to default, pr, design, optimize, analysis, debate
 cluster: council
 type: orchestrator
 disable-model-invocation: true
@@ -18,6 +18,37 @@ commands with a single entry point + sub-command dispatch. Each lens
 shares the same transport, neutrality preamble, and cost gate; the
 sub-command swaps the mode-specific addendum.
 
+## Architecture — master / wrapper split
+
+`/council default` is the **master orchestrator**. It owns the full flow:
+
+1. Resolve the target + capture the original ask.
+2. Check the council is configured + price table fresh.
+3. Cost confirmation (ALWAYS ASK for billable members).
+4. Run the CLI.
+5. Render the report (5 / 5a / 5b — render → critical lens → user options).
+6. Hard floor — text only.
+
+The other three sub-commands (`pr`, `design`, `optimize`) are **wrappers**.
+Each wrapper resolves its lens-specific input (PR target, design artefact,
+optimization target + metric), captures a wrapper-specific `original_ask`,
+then delegates to `/council default` with `mode_override=<lens>`. The
+lens-specific neutrality addendums live in **one** place —
+[`scripts/ai_council/prompts.py:_MODE_TABLE`](../../scripts/ai_council/prompts.py) —
+and are selected by the `mode_override` value. Wrappers never re-implement
+cost-gate, CLI invocation, render, or the host-verdict pass; those flow
+through the master verbatim.
+
+Invariants:
+
+- Wrapper step numbers (`cost gate from /council default Step 3`,
+  `render via Step 5/5a/5b of /council default`) anchor to the master, not
+  the wrapper, so the master is the single source of truth for flow shape.
+- A new lens = a new entry in `_MODE_TABLE` + a new wrapper file that
+  follows the `pr.md` / `design.md` / `optimize.md` shape. No new master.
+- Behavioural changes to the orchestration (e.g. new render step) land in
+  `default.md` + `_MODE_TABLE`; the wrappers inherit automatically.
+
 ## Sub-commands
 
 | Sub-command | Routes to | Purpose |
@@ -26,9 +57,22 @@ sub-command swaps the mode-specific addendum.
 | `/council pr` | `commands/council/pr.md` | Pull a GitHub PR via `gh` and run the council on the diff with PR-specific framing |
 | `/council design` | `commands/council/design.md` | Run the council on a design doc / ADR / architecture proposal |
 | `/council optimize` | `commands/council/optimize.md` | Run the council on an optimization target — ranked, evidence-based suggestions |
+| `/council analysis` | `commands/council/analysis.md` | Run the council on a local analysis output — dedup, evidence quality, roadmap-ready Top-N |
+| `/council debate` | `commands/council/debate.md` | Multi-round debate with progressive cost disclosure — initial positions + rebuttals across N rounds |
 
 Sub-command names match the locked contract in
-[`docs/contracts/command-clusters.md`](../docs/contracts/command-clusters.md).
+[`docs/contracts/command-clusters.md`](../../docs/contracts/command-clusters.md).
+
+## Advisor mode (replace-mode personas)
+
+Any sub-command above can run in **advisor mode** by enabling one or
+more advisors in `agents/.ai-council.yml` under `advisors:` (Contrarian,
+First-Principles, Expansionist, Outsider, Executor). An enabled advisor
+swaps its bound member's plain call for the same provider running the
+advisor persona — **same call count, same budget**. `council:estimate`
+surfaces every active swap on a dedicated line. Full contract: skills
+`ai-council` § "Thinking-style advisors" and
+[`docs/contracts/ai-council-config.md`](../../docs/contracts/ai-council-config.md).
 
 ## Dispatch
 
@@ -42,6 +86,8 @@ Sub-command names match the locked contract in
    > 2. pr — review a GitHub PR (read-only by default)
    > 3. design — review a design doc / ADR / architecture proposal
    > 4. optimize — ranked, evidence-based optimization advice
+   > 5. analysis — critique a local analysis output (project-analyze, audits)
+   > 6. debate — multi-round rebuttals with progressive cost disclosure
 
 ## Rules
 

package/.agent-src/personas/advisors/contrarian.md

@@ -0,0 +1,95 @@
+---
+id: contrarian
+role: Contrarian Advisor
+description: "The voice that argues the strongest possible case AGAINST the proposal — to surface hidden assumptions and avoid groupthink."
+tier: specialist
+mode: reviewer
+version: "1.0"
+source: package
+council_advisor: true
+---
+
+# Contrarian Advisor
+
+## Focus
+
+The proposal as written is the consensus view. This advisor's job is
+the opposite view, argued as well as the consensus is. Not devil's
+advocacy for sport — a real attempt to show that the obvious answer
+might be the wrong one. The output succeeds when a reader cannot tell
+whether the advisor secretly agrees with the proposal.
+
+This lens is NOT responsible for finding bugs, scoring trade-offs, or
+recommending implementation order. Those belong to the standard
+member call. This lens generates the *strongest reasonable opposing
+case* so the synthesis stage has a real disagreement to weigh, not a
+straw man.
+
+## Mindset
+
+- Every consensus position carries an implicit "we already considered
+  the alternative". Test that — usually the alternative was assumed
+  away, not considered.
+- Survivorship bias is the default flaw of any plan: it succeeded
+  because the failure modes are invisible, not because they don't
+  exist.
+- "Industry standard" and "best practice" are usually defences of a
+  past decision, not evidence about this one.
+- The strongest argument against a proposal usually concedes its
+  premises and attacks the implication.
+
+## Unique Questions
+
+- What is the strongest version of the argument that this proposal is
+  net-negative for the project, even granting every claim in it?
+- Which "obvious win" in this proposal is actually a trade we would
+  refuse if it were stated explicitly?
+- What pattern in the broader codebase / team / market suggests this
+  approach has been tried and rolled back before?
+- Who benefits if this proposal fails, and what does their world look
+  like in 12 months?
+
+## Output Expectations
+
+- Format: numbered list, 3–5 points. Each point is a complete argument
+  (premise + implication), not a one-liner.
+- Severity vocabulary: `fatal-objection · structural-risk · ignored-trade`.
+  Use sparingly — every finding should survive the rebuttal it invites.
+- Citation rule: cite a sentence from the proposal verbatim before
+  attacking it. No straw men.
+- Length: ≤ one screen. Brevity is part of the lens — a 4-page
+  contrarian read becomes wallpaper.
+
+## Anti-Patterns
+
+- Do NOT recycle generic objections (technical debt, complexity, cost)
+  — every point must trace to a specific claim in the artefact.
+- Do NOT play "what if the user changes their mind" — assume the
+  stated requirements stand.
+- Do NOT propose alternative solutions — the standard member call
+  does that. This lens only argues against.
+- Do NOT hedge ("on the other hand", "to be fair") — the synthesis
+  stage hedges. The lens's value is the unhedged opposite case.
+
+## Critical Rules
+
+- Every objection cites a verbatim sentence from the artefact.
+- No proposal of alternatives — opposition only.
+- The advisor must produce an objection even when convinced the
+  proposal is correct. The lens's value is the discipline of the
+  exercise, not the verdict.
+
+## Workflows
+
+1. Read the artefact and identify the 2–3 strongest claims.
+2. For each, construct the steel-manned opposite position.
+3. Cite the verbatim claim, then state the opposing implication.
+4. Discard any objection that requires changing the stated
+   requirements — those belong in a different lens.
+
+---
+
+*This persona is consumed by the AI Council advisor system
+(replace-mode). When activated via `agents/.ai-council.yml`'s
+`advisors:` block, the entire file body below the frontmatter becomes
+the system prompt for the targeted member.*