ai-consultants 2.21.1 → 2.23.0

package/.env.example

@@ -0,0 +1,428 @@
+# =============================================================================
+# AI Consultants - Environment Variables
+# =============================================================================
+# Copy this file to .env and customize as needed.
+# All variables have sensible defaults - only override what you need.
+#
+# IMPORTANT: At least 2 consultants must be enabled for the system to work.
+#
+# Export variables before running, or source this file:
+#   source .env && ./scripts/consult_all.sh "Your question"
+#
+# For detailed setup instructions, see: docs/SETUP.md
+
+# =============================================================================
+# API KEYS & AUTHENTICATION
+# =============================================================================
+# Each CLI tool requires its own authentication. Set the appropriate API keys
+# or use the CLI's built-in auth flow.
+
+# Google Gemini API key (only needed for API mode; the agy CLI uses OAuth)
+# Get yours at: https://makersuite.google.com/app/apikey
+# CLI mode uses the Antigravity CLI (agy); sign in by running `agy` once.
+# GEMINI_API_KEY=your-google-api-key
+
+# OpenAI API Key (required for Codex)
+# Get yours at: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=sk-your-openai-api-key
+
+# Mistral API Key
+# Get yours at: https://console.mistral.ai/api-keys/
+# MISTRAL_API_KEY=your-mistral-api-key
+
+# Anthropic API Key (for Claude API mode or synthesis)
+# Get yours at: https://console.anthropic.com/settings/keys
+# ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key
+
+
+# =============================================================================
+# API-BASED CONSULTANT KEYS
+# =============================================================================
+# These are required for the API-based consultants (Qwen3, GLM, Grok, DeepSeek)
+
+# Qwen3 (Alibaba DashScope) - The Analyst
+# Get yours at: https://dashscope.console.aliyun.com/
+# QWEN3_API_KEY=your_dashscope_api_key
+
+# GLM (Zhipu AI) - The Methodologist
+# Get yours at: https://open.z.ai/
+# GLM_API_KEY=your_zhipu_api_key
+
+# Grok (xAI) - The Provocateur
+# Get yours at: https://console.x.ai/
+# GROK_API_KEY=your_xai_api_key
+
+# DeepSeek - The Code Specialist
+# Get yours at: https://platform.deepseek.com/
+# DEEPSEEK_API_KEY=your_deepseek_api_key
+
+# MiniMax - The Pragmatic Optimizer (v2.10)
+# Get yours at: https://platform.minimax.io/user-center/basic-information/interface-key
+# MINIMAX_API_KEY=your_minimax_api_key
+
+# =============================================================================
+# ENABLED CONSULTANTS
+# =============================================================================
+# Set to "false" to disable a consultant you haven't configured.
+# MINIMUM 2 consultants must be enabled for comparison/voting to work.
+
+# CLI-based consultants (default: enabled)
+ENABLE_GEMINI=true
+ENABLE_CODEX=true
+ENABLE_MISTRAL=true
+ENABLE_CURSOR=true
+ENABLE_KIMI=true
+ENABLE_QWEN3=true
+ENABLE_MINIMAX=true
+ENABLE_CLAUDE=true
+
+# API-only consultants (default: disabled - require API keys)
+ENABLE_GLM=false
+ENABLE_GROK=false
+ENABLE_DEEPSEEK=false
+
+# =============================================================================
+# CLI/API MODE SWITCHING (v2.6+)
+# =============================================================================
+# 6 agents support switching: Gemini, Codex, Claude, Mistral, Qwen3, MiniMax
+# When API mode is enabled, CLI mode is automatically disabled.
+
+# GEMINI_USE_API is auto-resolved when left UNSET (v2.15.1): API mode if
+# GEMINI_API_KEY is present (no CLI install / OAuth needed — best for npm/npx),
+# else the agy CLI. Leave it commented to keep auto-resolution; uncomment only
+# to force a specific mode (an explicit value disables auto-detection).
+# GEMINI_USE_API=false       # Force Google AI API (true) or agy CLI (false)
+# Leave the following commented to keep CLI-first auto-resolution (CLI wins
+# when installed; API is the fallback for a key with no CLI). Uncomment only
+# to force a specific transport for that agent.
+# CODEX_USE_API=false          # Use OpenAI API instead of codex CLI
+# CLAUDE_USE_API=false         # Use Anthropic API instead of claude CLI
+# MISTRAL_USE_API=false        # Use Mistral API instead of vibe CLI
+# QWEN3_USE_API=false          # Use qwen CLI (default) or DashScope API (v2.7)
+# MINIMAX_USE_API=false      # Unset = API for legacy key users, otherwise mmx CLI
+
+# API endpoints (override if using custom endpoints)
+# GEMINI_API_URL=https://generativelanguage.googleapis.com/v1beta/models
+# CODEX_API_URL=https://api.openai.com/v1/chat/completions
+# CLAUDE_API_URL=https://api.anthropic.com/v1/messages
+# MISTRAL_API_URL=https://api.mistral.ai/v1/chat/completions
+# QWEN3_API_URL=https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation
+
+# =============================================================================
+# MODEL CONFIGURATION (June 2026 premium defaults)
+# =============================================================================
+
+# Gemini - The Architect (CLI mode via Antigravity CLI: agy)
+GEMINI_MODEL="Gemini 3.1 Pro (High)"
+GEMINI_TIMEOUT=180
+GEMINI_CMD=agy
+# API-mode model ID (only used when GEMINI_USE_API=true)
+GEMINI_API_MODEL=gemini-3.1-pro-preview
+
+# Codex - The Pragmatist
+CODEX_MODEL=gpt-5.5
+CODEX_TIMEOUT=180
+CODEX_CMD=codex
+
+# Mistral Vibe - The Devil's Advocate
+MISTRAL_MODEL=mistral-large-3
+MISTRAL_TIMEOUT=180
+MISTRAL_CMD=vibe
+
+# Cursor - The Integrator
+CURSOR_MODEL=composer-2.5
+CURSOR_TIMEOUT=180
+CURSOR_CMD=agent
+
+# Kimi - The Eastern Sage (K3 via Kimi Code CLI)
+KIMI_MODEL=kimi-code/k3
+KIMI_TIMEOUT=180
+KIMI_CMD=kimi
+
+# Claude - The Synthesizer
+CLAUDE_MODEL=claude-opus-4-8
+CLAUDE_TIMEOUT=240
+CLAUDE_CMD=claude
+
+# Qwen3 - The Analyst (CLI/API switchable v2.7)
+QWEN3_MODEL=qwen3.7-max
+QWEN3_TIMEOUT=180
+QWEN3_CMD=qwen
+
+# =============================================================================
+# API-BASED CONSULTANT CONFIGURATION
+# =============================================================================
+
+# GLM - The Methodologist
+GLM_MODEL=glm-5.2
+GLM_TIMEOUT=180
+GLM_API_URL=https://api.z.ai/api/coding/paas/v4/chat/completions
+
+# Grok - The Provocateur
+GROK_MODEL=grok-4.5
+GROK_TIMEOUT=180
+GROK_API_URL=https://api.x.ai/v1/chat/completions
+
+# DeepSeek - The Code Specialist
+DEEPSEEK_MODEL=deepseek-v4-pro
+DEEPSEEK_TIMEOUT=180
+DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions
+
+# MiniMax - The Pragmatic Optimizer (CLI via mmx by default, v2.21; API opt-in)
+MINIMAX_CMD=mmx
+MINIMAX_MODEL=MiniMax-M2.7
+MINIMAX_TIMEOUT=180
+MINIMAX_API_URL=https://api.minimax.io/v1/chat/completions
+
+# Response formats for API-based consultants
+QWEN3_FORMAT=qwen
+GLM_FORMAT=openai
+GROK_FORMAT=openai
+DEEPSEEK_FORMAT=openai
+MINIMAX_FORMAT=openai
+
+# =============================================================================
+# FEATURES v2.8
+# =============================================================================
+
+# Defaults used when --preset / --strategy are omitted
+DEFAULT_PRESET=balanced
+DEFAULT_STRATEGY=majority
+
+# The invoking integration normally sets this per run for self-exclusion.
+INVOKING_AGENT=unknown
+
+# Personas: specialized roles for each consultant
+ENABLE_PERSONA=true
+
+# Auto-synthesis: automatic synthesis of all responses
+ENABLE_SYNTHESIS=true
+SYNTHESIS_CMD=claude
+# Optional synthesis-specific model. Empty delegates model selection to the CLI.
+SYNTHESIS_MODEL=
+SYNTHESIS_EXTRACT_FIELDS=true
+SYNTH_MAX=10
+
+# Multi-Agent Debate (MAD): cross-critique rounds
+ENABLE_DEBATE=false
+DEBATE_ROUNDS=1              # 1 = no debate, 2-3 = with cross-critique
+
+# Peer Review: anonymous evaluation
+ENABLE_PEER_REVIEW=false
+PEER_REVIEW_MIN_RESPONSES=3
+REVIEWS_PER_CONSULTANT=3
+
+# Panic Mode: auto-rigor when uncertainty detected
+ENABLE_PANIC_MODE=auto
+PANIC_CONFIDENCE_THRESHOLD=5
+PANIC_EXTRA_DEBATE_ROUNDS=1
+PANIC_KEYWORDS="uncertain|maybe|not sure|possibly|unclear|depends|hard to say|difficult to determine"
+
+# Dynamic orchestration: choose how the panel deliberates
+# auto | fixed | quick | converge | adversarial | tournament | exhaustive
+ORCHESTRATION_MODE=auto
+CONVERGENCE_MAX_ROUNDS=4
+CONVERGENCE_TARGET_CONSENSUS=75
+CONVERGENCE_STALL_EPSILON=5
+ENABLE_ADVERSARIAL_VERIFY=true
+
+# Debate optimization: avoid extra rounds when the panel already agrees
+ENABLE_DEBATE_OPTIMIZATION=true
+DEBATE_CONFIDENCE_SPREAD_THRESHOLD=2
+DEBATE_USE_SUMMARIES=true
+
+# Health gate and quorum: validate the live panel before spending on a full run
+ENABLE_HEALTH_GATE=false       # Adds one small ping per selected consultant
+HEALTH_GATE_TIMEOUT=30
+QUORUM_MIN=2
+QUORUM_ACTION=warn             # warn or stop
+
+# =============================================================================
+# SEMANTIC CACHING (v2.3)
+# =============================================================================
+
+ENABLE_SEMANTIC_CACHE=true
+CACHE_TTL_HOURS=24
+# CACHE_DIR=/custom/cache/path
+
+# API retry and rate-limit controls
+API_BASE_BACKOFF=2
+API_MAX_BACKOFF=60
+API_RATE_LIMIT=30
+
+# Optional response limits by question category
+ENABLE_RESPONSE_LIMITS=false
+MAX_RESPONSE_TOKENS_BY_CATEGORY=QUICK_SYNTAX:200,CODE_REVIEW:800,BUG_DEBUG:800,ARCHITECTURE:1000,SECURITY:1000,DATABASE:600,GENERAL:500
+
+# =============================================================================
+# BUDGET ENFORCEMENT (v2.4, opt-in)
+# =============================================================================
+
+ENABLE_BUDGET_LIMIT=false
+BUDGET_ACTION=warn           # warn or stop
+MAX_SESSION_COST=1.00
+
+# =============================================================================
+# SMART ROUTING
+# =============================================================================
+
+# Question classification (required for smart routing)
+ENABLE_CLASSIFICATION=true
+CLASSIFICATION_MODE=pattern  # pattern (fast) or llm (accurate)
+
+# Smart routing: select consultants based on question category
+ENABLE_SMART_ROUTING=false
+MIN_AFFINITY=7               # Minimum affinity score (1-10) to include
+
+# Cost-aware routing (v2.3)
+ENABLE_COST_AWARE_ROUTING=false
+USE_ECONOMIC_MODELS_FOR_SIMPLE=true
+COMPLEXITY_THRESHOLD_SIMPLE=3
+COMPLEXITY_THRESHOLD_MEDIUM=6
+FALLBACK_CONFIDENCE_THRESHOLD=7
+
+# Capability-aware routing & voting (v2.20, opt-in): weight votes and rank the
+# panel by each consultant's capability on the quality axis a question stresses
+# (intelligence or taste, per references/affinity.json 'category_axis'). cost is
+# a composition/budget axis only, never a vote weight.
+ENABLE_CAPABILITY_WEIGHTING=false   # capability-weighted voting
+ENABLE_CAPABILITY_ROUTING=false     # capability-aware panel composition
+CAPABILITY_WEIGHT_STRENGTH=10       # higher = gentler nudge: weight = conf*(S+cap)/S
+CAPABILITY_DEFAULT=5                # fallback capability for a missing consultant/axis
+
+# Stance-based semantic consensus (v2.21, opt-in): the panel picks from a shared
+# enumerated stance set so agreement is scored by exact match instead of lexical
+# similarity. Adds ~1 LLM call per run; degrades to the lexical cluster on any
+# failure, so it is always safe to enable.
+ENABLE_STANCE_CONSENSUS=false
+STANCE_MAX_OPTIONS=5                # max stance options generated per question
+STANCE_TIMEOUT=60                  # seconds for the stance-generation call (guards a hang)
+
+# =============================================================================
+# COST MANAGEMENT
+# =============================================================================
+
+ENABLE_COST_TRACKING=true
+WARN_AT_COST=0.50            # Warning threshold (USD)
+ENABLE_RELIABILITY_TRACKING=true
+# COST_TRACKING_FILE=/custom/data/costs.json
+# RELIABILITY_FILE=/custom/data/reliability.json
+# COST_RATES_FILE=/custom/config/cost_rates.json
+
+# =============================================================================
+# SESSION MANAGEMENT
+# =============================================================================
+
+SESSION_CLEANUP_DAYS=7       # Auto-cleanup sessions older than N days
+# SESSION_DIR=/custom/state/sessions
+
+# =============================================================================
+# INTERACTIVE MODE
+# =============================================================================
+
+ENABLE_PROGRESS_BARS=true    # Show progress bars during consultation
+ENABLE_EARLY_TERMINATION=true # Allow Ctrl+C to stop with partial results
+
+# =============================================================================
+# PRE-FLIGHT CHECKS
+# =============================================================================
+
+ENABLE_PREFLIGHT=false       # Run health check before each consultation
+PREFLIGHT_QUICK=true         # Quick mode: CLI check only, skip API test
+
+# =============================================================================
+# RETRY & TIMEOUT
+# =============================================================================
+
+MAX_RETRIES=2                # Max retry attempts on failure
+RETRY_DELAY_SECONDS=5        # Pause between retries
+LAUNCH_STAGGER_MAX_SECONDS=2
+
+# Output directory base
+# DEFAULT_OUTPUT_DIR_BASE=/custom/cache/consultations
+
+# Live doctor probe timeout
+DOCTOR_LIVE_TIMEOUT=45
+
+# =============================================================================
+# CONTEXT HANDOFF & TOKEN OPTIMIZATION
+# =============================================================================
+
+TOKEN_OPTIMIZATION_MODE=ast
+MAX_CONTEXT_FILE_BYTES=8000
+ENABLE_AST_EXTRACTION=true
+ENABLE_SYMBOL_COMPRESSION=false
+ENABLE_SEMANTIC_CHUNKING=true
+CHUNK_MAX_TOKENS=500
+CHUNK_OVERLAP_LINES=5
+CHUNK_PRIORITY_KEYWORDS=main,export,public,api,handler,controller
+INCLUDE_DOCSTRINGS=true
+INCLUDE_CRITICAL_COMMENTS=true
+MAX_BODY_SUMMARY_LINES=3
+MIN_IDENTIFIER_LENGTH=8
+PRESERVE_EXPORTS=true
+USE_COMPACT_PROMPTS=true
+FORCE_PROJECT_TREE=false
+ENABLE_SELECTIVE_CONTEXT=false
+MAX_FILES_PER_CONSULTANT=5
+
+# =============================================================================
+# REPORTING & STORAGE
+# =============================================================================
+
+ENABLE_COMPACT_REPORT=true
+REPORT_MAX_JSON_LINES=50
+# RATE_LIMIT_DIR=/custom/cache/ratelimit
+# CHUNK_TEMP_DIR=/custom/cache/chunks
+
+# =============================================================================
+# CUSTOM ROUTING & PERSONAS
+# =============================================================================
+
+# AFFINITY_FILE=/path/to/affinity.json
+
+# Each consultant supports _PERSONA_ID (1-21), _PERSONA (custom prompt), and
+# _PERSONA_NAME (custom display name). Uncomment only the overrides you need.
+# GEMINI_PERSONA_ID=1
+# CODEX_PERSONA_ID=2
+# MISTRAL_PERSONA_ID=3
+# CURSOR_PERSONA_ID=5
+# KIMI_PERSONA_ID=20
+# CLAUDE_PERSONA_ID=18
+# QWEN3_PERSONA_ID=6
+# GLM_PERSONA_ID=7
+# GROK_PERSONA_ID=8
+# DEEPSEEK_PERSONA_ID=17
+# MINIMAX_PERSONA_ID=21
+# GEMINI_PERSONA=Custom persona instructions
+# GEMINI_PERSONA_NAME=Custom persona name
+# CODEX_PERSONA=Custom persona instructions
+# CODEX_PERSONA_NAME=Custom persona name
+# MISTRAL_PERSONA=Custom persona instructions
+# MISTRAL_PERSONA_NAME=Custom persona name
+# CURSOR_PERSONA=Custom persona instructions
+# CURSOR_PERSONA_NAME=Custom persona name
+# KIMI_PERSONA=Custom persona instructions
+# KIMI_PERSONA_NAME=Custom persona name
+# CLAUDE_PERSONA=Custom persona instructions
+# CLAUDE_PERSONA_NAME=Custom persona name
+# QWEN3_PERSONA=Custom persona instructions
+# QWEN3_PERSONA_NAME=Custom persona name
+# GLM_PERSONA=Custom persona instructions
+# GLM_PERSONA_NAME=Custom persona name
+# GROK_PERSONA=Custom persona instructions
+# GROK_PERSONA_NAME=Custom persona name
+# DEEPSEEK_PERSONA=Custom persona instructions
+# DEEPSEEK_PERSONA_NAME=Custom persona name
+# MINIMAX_PERSONA=Custom persona instructions
+# MINIMAX_PERSONA_NAME=Custom persona name
+
+# Calibration judge commands
+TASTE_JUDGE_CMD=
+JUDGE_CLI=claude
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+
+LOG_LEVEL=INFO               # DEBUG, INFO, WARN, ERROR

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model AI deliberation system that queries up to 11 AI
 
 **Self-Exclusion**: The invoking agent is automatically excluded from the panel to prevent self-consultation. Claude Code won't query Claude, Codex CLI won't query Codex, etc.
 
-**Version**: 2.21.1
+**Version**: 2.23.0
 
 ## Distribution
 
@@ -64,8 +64,7 @@ ai-consultants/
 │       ├── costs.sh            # Cost tracking + response limits
 │       ├── cache.sh            # Semantic caching (v2.3)
 │       ├── api_query.sh        # API mode query execution (v2.6)
-│       ├── progress.sh         # Progress bars
-│       └── reflection.sh       # Self-reflection + judge step
+│       └── progress.sh         # Progress bars
 ├── references/
 │   ├── configuration.md      # Full configuration reference
 │   └── details.md            # Presets, strategies, best practices
@@ -194,7 +193,7 @@ Functions in `lib/common.sh`:
 ### Configuration Presets
 ```bash
 # Quality Tier Presets (v2.5)
-./scripts/consult_all.sh --preset max_quality "question"  # All + premium models + debate
+./scripts/consult_all.sh --preset max_quality "question"  # 8 of 11 consultants + premium models + peer review
 ./scripts/consult_all.sh --preset medium "question"       # 4 consultants + standard models
 ./scripts/consult_all.sh --preset fast "question"         # 2 consultants + economy models
 
@@ -252,12 +251,6 @@ Process:
 3. Aggregate peer scores to identify strongest arguments
 4. De-anonymize in final report
 
-### Judge Step (Overconfidence Detection)
-Functions in `lib/reflection.sh`:
-- `judge_response()` - Evaluates single response for overconfidence
-- `heuristic_overconfidence_check()` - Fast fallback without LLM
-- `judge_all_responses()` - Batch evaluation
-
 ## v2.9 Features
 
 ### Kimi CLI Support
@@ -410,7 +403,7 @@ get_model_for_tier "claude" "economy"   # → claude-haiku-4-5
 Three new presets leverage the model tiers:
 
 ```bash
-# Maximum quality - all premium models + debate + reflection
+# Maximum quality - all premium models + debate + peer review
 ./scripts/consult_all.sh --preset max_quality "critical architecture decision"
 
 # Balanced quality - standard models, 4 consultants, light debate
@@ -802,6 +795,27 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v2.23.0
+- **`lib/reflection.sh` deleted (452 lines) and `ENABLE_REFLECTION` / `REFLECTION_CYCLES` removed.** The module was never sourced — `grep -rn 'reflection\.sh' scripts/` matched only the file's own header — so the generate-critique-refine loop had never executed. The two flags were declared at `config.sh` and exported by four presets (`high-stakes`, `max_quality`, `fast`, `_disable_all_consultants`) with no consumer anywhere. It had also aged past the codebase: `_exec_consultant` hardcoded a Gemini/Codex/Mistral case (3 of 11 consultants; the rest hit `*) return 1`) and its Gemini branch still used the pre-`agy` CLI syntax retired in v2.15.0 — so wiring it up as written would have produced partial reflection with a broken Gemini path. Removed rather than implemented because v2.16's `converge`/`adversarial` shapes already run critique-refine off measured consensus rather than a fixed cycle count. Worth noting for archaeology: the module was *maintained* in at least three review passes (v2.15.1 de-fencing, the `--model` parity change, the v2.10.9 `((var++))` sweep) — effort spent on code that never ran.
+- **The release gate had been red since 2.22.0 and nobody could see it.** `scripts/release.sh:26` sources `lib/common.sh` → `config.sh` → `load_user_config` *before* `npm test` at line 194, so `_apply_env_file`'s `export "$key=$value"` put the maintainer's entire `~/.config/ai-consultants/.env` into the test environment. Two suites were not hermetic against that, and the first aborted the run before the second could surface:
+  - **`test_user_config.sh`** — `test_xdg_fallback` (Test 6) unsets `AI_CONSULTANTS_CONFIG_DIR` in the suite's own shell (required, to assert the XDG branch) and `_reset_state` never restored it, so the unset leaked into all 22 later tests, which then read the *real* user config. Fixed by re-exporting an empty temp dir in `_reset_state`, making isolation order-independent; tests that legitimately override the dir per-invocation are unaffected. Plus the whole `*_USE_API` set unset at suite top (the guard `test_configure.sh` already carried), and `ENABLE_KIMI`/`GROK_API_URL` (Test 27) and `GEMINI_MODEL`/`PANIC_KEYWORDS` (Test 28) unset inside their subshells — those assert on *real* var names and `load_user_config` lets the environment win over the file by design, so with `config.sh` pre-sourced the file under test was never consulted.
+  - **`test_configure.sh`** — `run_clean_configure` scrubbed the nine API keys but no settings, while `configure`'s `has_explicit_value` reads any ambient value as a deliberate pin. An exported `DEFAULT_PRESET` therefore overrode the value Tests 6 and 10 had just written into the file they assert on. The scrub set is now derived from `configure --show-parameters` — configure's own contract — with a hard failure if that list comes back empty, so the scrub can never silently degrade to a no-op. **Verified pre-existing**: the same two assertions fail at `2ac18d4` (the v2.22.0 release commit) under the same conditions, via a throwaway worktree.
+- **`test_functions.sh` was under-reporting failures across the whole file.** `run_tests` scores a test by its exit status — that of its LAST command — so a failing assertion followed by a passing one printed `FAIL`, incremented nothing, and let the suite exit 0. 8 of the 13 test functions run more than one assertion and none accumulated a result. The five `assert_*` helpers now set `_ASSERT_FAILED` on every failure path and `run_tests` fails a test when either that flag or the exit status is non-zero. **Caught by trying to make the new pin fail**: the first version of `test_known_feature_flags_in_sync` printed `FAIL: ... Actual: PHANTOM_FEATURE` while the suite still reported "All tests passed". Verified against a pre-existing test by breaking the first of three assertions in `test_case_conversion` — previously green, now correctly red.
+- **`KNOWN_FEATURE_FLAGS` synced (9 → 27) and pinned.** `_discover_custom_api_agents` (`consult_all.sh:48`) walks `env` and enrolls any `ENABLE_X=true` as a consultant when `X_API_URL` is set and `X` is absent from the registry, so the 18 missing flags — `PEER_REVIEW`, `HEALTH_GATE`, `SEMANTIC_CACHE`, … — were latent phantom consultants. Measured drift: 18 missing, 0 stale. `test_known_feature_flags_in_sync` derives the expected set from `config.sh`'s top-level `ENABLE_*` declarations minus `KNOWN_CLI_AGENTS`/`KNOWN_API_AGENTS` and asserts both directions, so the next added flag fails the build. (Checked that the `^ENABLE_` grep misses nothing declared only inside functions — the sole extra hit was `AGENTNAME`, from the convention's doc comment.)
+- **Preset tables were documenting a mode that stopped being the default in v2.16.** Found by the `/code-review max` pass on the removal branch: renaming the README column from "Reflection" to "Peer Review" turned a code-enforced "No" into a false claim, because `_disable_all_consultants` exported `ENABLE_REFLECTION=false` — the line this release deletes — whereas nothing ever clears `ENABLE_PEER_REVIEW`. Combined with `consult_all.sh:285` force-enabling peer review for the adversarial shape, `--preset medium` on a SECURITY question runs a full billed peer-review round the table promised it would not. The Debate column was stale for the same reason (`DEBATE_ROUNDS` is only read under `ORCHESTRATION_MODE=fixed`). Both tables now state only what the preset pins, with the planner's role called out. Also corrected `max_quality`'s "All consultants" → 8 of 11, which contradicted the README table in the same commit.
+
+### v2.22.0
+- Added the public `ai-consultants configure` / `config` subcommand. Automatic mode detects every current consultant, uses CLI-first transport selection with API fallback when credentials are available, persists to the XDG user config directory, preserves custom values and secrets while refreshing availability-derived `ENABLE_*` flags, backs up rewrites, and keeps files at mode 600.
+- Replaced the stale 1,092-line v2.0 configurator with a compact implementation whose accepted parameter surface is derived from `.env.example`. `--set KEY=VALUE` supports repeatable automation and participates in detection, `--interactive` reviews credentials/transports/panel selection, `--advanced` reviews every parameter, `--show-parameters` exposes the contract, and side-effect-free `--dry-run` redacts secrets.
+- Added `test_configure.sh` (60 assertions) covering public routing, runtime-wide template parity, full-roster detection, API fallback, override precedence/empty values, transport provenance, advanced defaults, export preservation, dry-run isolation/redaction, symlink refusal, backups/permissions, and rejection of removed settings. The npm-pack smoke path now includes `.env.example` and exercises both `init` and `configure` from the installed tarball.
+- **Three interactive/provenance bugs fixed before the subcommand ever shipped** (found in review; none reached a tagged release):
+  - **`--interactive` aborted on the first Enter.** `prompt_value` ended both branches with `[[ -n "$reply" ]] && set_value …`. An empty reply — the documented "press Enter to keep" path — made that `&&` list return 1, and since it was the function's last command, `prompt_value` returned 1; under `set -e` the plain call site in the `for` loop killed the script (exit 1, nothing written). Now an explicit `if` block, so an empty reply returns 0.
+  - **`--advanced` silently wrote garbage.** `done < <(list_parameters)` redirects fd 0 for the *whole loop body*, so `prompt_value`'s nested `read -r -p` consumed the parameter list instead of the terminal — each prompt took the *next parameter's name* as the user's answer (observed: `AFFINITY_FILE` ← `ANTHROPIC_API_KEY`). Fixed with the standard fd-separation idiom (`read … <&3` / `done 3< <(…)`).
+  - **`init` then `configure` disabled four consultants.** `init` copies `.env.example` verbatim, and the template carried uncommented `CODEX_USE_API=false` / `CLAUDE_USE_API` / `MISTRAL_USE_API` / `QWEN3_USE_API`. `has_explicit_value` reads any unmarked value as a user pin, so `configure_switchable` took the explicit-`false` branch: with no CLI and a valid API key the consultant was disabled outright instead of resolving to API. Fixed in the *template*, not the provenance logic — the four switches are now commented out, matching the convention `GEMINI_USE_API`/`MINIMAX_USE_API` already established (commented = auto-resolve, uncommented = force). CLI-first is unaffected: an installed CLI still wins over a present key.
+- **Backup names are now collision-proof.** `${OUTPUT_FILE}.backup.$(date +%Y%m%d_%H%M%S)` is only second-precise, so two runs inside one second resolved to the same path and the second `cp` clobbered the first backup — losing the user's *original* config while keeping a machine-generated one. Now `mktemp "…backup.<ts>.XXXXXX"`, which claims the name atomically (also making concurrent runs safe). Note the collision is unreachable from a sequential test — a real run takes ~1-8s, longer than the granularity — so the regression test stubs `date` on `PATH` to freeze the clock; the backup line is the only `date` caller in this path.
+- **`test_configure.sh` made hermetic against an ambient config environment — `scripts/release.sh` could not run its own gate.** `config.sh` auto-resolves `GEMINI_USE_API`/`MINIMAX_USE_API` and **exports** them; `configure.sh::has_explicit_value` treats any ambient value as a deliberate user pin. `release.sh` sources `lib/common.sh` (→ `config.sh`) *before* running `npm test`, so the gate inherited pinned transports: Tests 4 and 11 failed under `release.sh` while passing from a clean shell — a "flaky" result that was in fact deterministic per-environment. The suite now `unset`s the whole switchable `*_USE_API` set at the top (one place, covering all 10 configure invocations; only the two auto-resolved ones actually leak today, but the set is cleared so a future auto-resolution — as MiniMax gained in v2.21 — cannot silently reopen it). Same class as the v2.21.0 `test_user_config.sh` fix. Verified green both from a clean shell and under `source lib/common.sh; npm test`. Latent since `test_configure.sh` was introduced; it never affected the shipped runtime, only the release gate.
+- Deprecated `setup_wizard.sh` to a compatibility forwarder. Corrected `GOOGLE_API_KEY` to `GEMINI_API_KEY`, removed legacy `/tmp` overrides from the starter template, completed advanced settings/persona coverage, and fixed safe parsing of unquoted `.env` inline comments.
+
 ### v2.21.1
 - **Kimi upgraded to K3.** `KIMI_MODEL` now defaults to `kimi-code/k3`; premium, standard, and economy tiers all resolve to the same K3 alias.
 - **Model selection is now real, not metadata-only.** `query_kimi.sh` passes `--model "$KIMI_MODEL"` to the CLI, overriding a stale user-level Kimi default. A dedicated offline regression test captures the CLI arguments and validates response metadata; a live K3 smoke test returned a structured response with confidence 10.

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v2.21.1
+# AI Consultants v2.23.0
 
 > **A harness for every question.** A panel of up to 11 frontier models that writes its own playbook per question — fan out, debate to convergence, cross-examine under adversarial review, or run a tournament — and checks its work before it reaches you.
 
-[![Version](https://img.shields.io/badge/version-2.21.1-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-2.23.0-blue.svg)](https://github.com/matteoscurati/ai-consultants)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude Code Skill](https://img.shields.io/badge/Claude%20Code-Skill-orange.svg)](https://docs.anthropic.com/en/docs/claude-code/skills)
 [![GitHub stars](https://img.shields.io/github/stars/matteoscurati/ai-consultants?style=social)](https://github.com/matteoscurati/ai-consultants)
@@ -428,11 +428,19 @@ Choose the right balance of quality, speed, and cost with model quality tiers.
 
 ### Tier Presets
 
-| Preset | Tier | Agents | Debate | Reflection | Use Case |
-|--------|------|--------|--------|------------|----------|
-| `max_quality` | Premium | 8 | 3 rounds | 2 cycles + peer review | Critical decisions |
-| `medium` | Standard | 4 | 1 round | No | General questions |
-| `fast` | Economy | 2 | No | No | Quick checks |
+| Preset | Tier | Agents | Use Case |
+|--------|------|--------|----------|
+| `max_quality` | Premium | 8 of 11 | Critical decisions |
+| `medium` | Standard | 4 | General questions |
+| `fast` | Economy | 2 | Quick checks |
+
+**Deliberation depth is not fixed by the preset.** Under the default
+`ORCHESTRATION_MODE=auto` the planner picks the shape per question, so the
+`DEBATE_ROUNDS` a preset pins applies only under `ORCHESTRATION_MODE=fixed`,
+and a `SECURITY`-classified question runs the adversarial shape — including a
+peer-review round — whatever preset you chose. `max_quality` additionally
+enables peer review outright; `medium` and `fast` do not *clear* it, so an
+enabled peer review carries into them.
 
 ### Models by Tier
 
@@ -479,8 +487,8 @@ Choose how many consultants to use:
 
 | Preset | Consultants | Tier | Use Case |
 |--------|-------------|------|----------|
-| `max_quality` | 8 + debate + reflection | Premium | Critical decisions |
-| `medium` | 4 + light debate | Standard | General questions |
+| `max_quality` | 8 of 11 (+ peer review) | Premium | Critical decisions |
+| `medium` | 4 | Standard | General questions |
 | `fast` | 2 | Economy | Quick checks |
 | `minimal` | 2 (Gemini + Codex) | Default | Quick questions, low cost |
 | `balanced` | 4 (+ Mistral + Cursor) | Default | Standard consultations |
@@ -513,13 +521,42 @@ Control how responses are combined:
 
 ### Environment Variables
 
-**Most users only need:**
+**Automatic configuration (recommended):**
 
 ```bash
-ai-consultants init           # creates ~/.config/ai-consultants/{config.sh,.env}
-$EDITOR ~/.config/ai-consultants/.env
+# Detect installed CLIs and available API keys, then write the persistent config
+ai-consultants configure
+
+# Review the consultant selection and transports interactively
+ai-consultants configure --interactive
+
+# Set any persistent parameter without opening an editor
+ai-consultants configure \
+  --set DEFAULT_PRESET=balanced \
+  --set ENABLE_DEBATE=true \
+  --set ORCHESTRATION_MODE=converge
+
+# Inspect the complete machine-readable parameter surface
+ai-consultants configure --show-parameters
 ```
 
+The configurator covers every persistent setting in `scripts/config.sh`, plus
+credentials, persona overrides, transport controls, advanced context knobs, and
+calibration commands. Existing custom values and secrets are preserved, while
+`ENABLE_*` flags are refreshed from detected availability (and can be pinned
+with `--set`). Rewrites create a private timestamped backup. Use `--advanced` to
+review every parameter or `--dry-run` to preview a redacted result.
+Auto-selected `*_USE_API` values are marked `# ai-consultants:auto`, allowing a
+later run to adapt when a CLI or credential changes. Environment variables,
+`--set`, and unmarked values remain explicit user choices.
+
+Enter credentials through `--interactive`/`--advanced` or export them before the
+run; avoid passing API keys through `--set`, where the shell may retain them in
+history or expose them in the process list.
+
+For a manual starter template instead, run `ai-consultants init` and edit
+`~/.config/ai-consultants/.env`.
+
 For ad-hoc overrides without persisting, the most common knobs:
 
 ```bash
@@ -688,6 +725,18 @@ Each consultation generates:
 
 ## Changelog
 
+### v2.23.0
+
+- **`ENABLE_REFLECTION` and `REFLECTION_CYCLES` removed.** The self-reflection module they controlled was never called by anything, so the settings had never affected a consultation — v2.16's `converge` and `adversarial` shapes already run critique-refine off measured consensus. **If you set either key**, remove it: `configure --set ENABLE_REFLECTION=...` now exits non-zero, and both keys are dropped when an existing `.env` is rewritten.
+- **The release gate works again.** Two test suites failed deterministically against any real user configuration, so no release since 2.22.0 could pass its own `npm test`.
+- **`npm test` no longer swallows failures.** A failing assertion followed by a passing one inside the same test function was counted as a pass, across 8 of 13 test functions.
+- **Feature flags can no longer be enrolled as consultants.** A registry that told feature flags apart from custom API agents was 18 entries out of date; it is now complete and pinned by a test.
+- **Preset tables corrected** — they described a debate and peer-review depth the code has not enforced since v2.16, and called `high-stakes`/`max_quality` "all consultants" when they enable 5 and 8 of 11. See the [v2.23.0 release note](docs/releases/v2.23.0.md).
+
+### v2.22.0
+
+- **`ai-consultants configure`**: a public automatic configurator. It detects your installed CLIs and API keys, picks CLI-first transports, and writes a private XDG config while preserving your existing settings and secrets. Drive it with repeatable `--set KEY=VALUE`, review it with `--interactive` / `--advanced`, or preview it with `--dry-run`. See the [v2.22.0 release note](docs/releases/v2.22.0.md).
+
 ### v2.21.1
 
 - **Kimi K3**: Kimi now defaults to `kimi-code/k3`, and the adapter passes the model explicitly with `--model`.
@@ -759,7 +808,7 @@ Each consultation generates:
 
 - **Claude consultant**: New consultant with "The Synthesizer" persona
 - **Self-exclusion**: Invoking agent automatically excluded from panel
-- **Presets**: Quick configuration with `--preset minimal/balanced/high-stakes/local`
+- **Presets**: Quick configuration with `--preset minimal/balanced/high-stakes/security`
 - **Doctor command**: Diagnostic and auto-fix tool
 - **Synthesis strategies**: `--strategy majority/risk_averse/security_first/compare_only`
 - **Confidence intervals**: Statistical confidence ranges (e.g., "8 +/- 1.2")

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (agy, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 2.21.1
+  version: 2.23.0
 ---
 
-# AI Consultants v2.21.1 - AI Expert Panel
+# AI Consultants v2.23.0 - AI Expert Panel
 
 **A harness for every question.** Convene a panel of AI "consultants" for coding questions — and let the engine pick *how* they deliberate: a quick read, a convergence loop, an adversarial refutation gate, a tournament, or an exhaustive sweep. Each consultant has a **configurable persona** that shapes its analysis.
 
@@ -100,13 +100,16 @@ Query is classified, then sent to consultants in parallel. Responses are scored,
 All settings use environment variables. Key toggles:
 
 ```bash
+ai-consultants configure     # Auto-detect CLIs/API keys and persist all settings
 ENABLE_DEBATE=true           # Multi-agent debate
 ENABLE_SYNTHESIS=true        # Automatic synthesis
 ENABLE_PANIC_MODE=auto       # Auto-rigor for uncertainty
 ENABLE_BUDGET_LIMIT=false    # Budget enforcement (v2.4)
 ```
 
-Enable opt-in consultants: `ENABLE_KIMI`, `ENABLE_QWEN3`, `ENABLE_CLAUDE`, `ENABLE_MINIMAX`.
+Use `ai-consultants configure --show-parameters` for the exact accepted keys,
+`--set KEY=VALUE` for repeatable automation, or `--advanced` to review all of
+them interactively.
 
 CLI/API switching: `GEMINI_USE_API`, `CODEX_USE_API`, `CLAUDE_USE_API`, `MISTRAL_USE_API`, `QWEN3_USE_API`.