ai-consultants 4.0.3 → 5.0.0

package/.env.example

@@ -250,7 +250,7 @@ MINIMAX_FORMAT=openai
 # =============================================================================
 
 # Defaults used when --preset / --strategy are omitted
-DEFAULT_PRESET=balanced
+# DEFAULT_PRESET=balanced
 DEFAULT_STRATEGY=coverage
 
 # The invoking integration normally sets this per run for self-exclusion.
@@ -335,15 +335,12 @@ ENABLE_RELIABILITY_TRACKING=true
 # SESSION MANAGEMENT
 # =============================================================================
 
-SESSION_CLEANUP_DAYS=7       # Auto-cleanup sessions older than N days
+SESSION_CLEANUP_DAYS=7       # Deprecated no-op; retained for v4.x compatibility
 # 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
+# Deprecated no-ops; retained for v4.x compatibility
+ENABLE_PROGRESS_BARS=true
+ENABLE_EARLY_TERMINATION=true
 
 # =============================================================================
 # PRE-FLIGHT CHECKS
@@ -383,10 +380,10 @@ INCLUDE_CRITICAL_COMMENTS=true
 MAX_BODY_SUMMARY_LINES=3
 MIN_IDENTIFIER_LENGTH=8
 PRESERVE_EXPORTS=true
-USE_COMPACT_PROMPTS=true
+USE_COMPACT_PROMPTS=true      # Deprecated no-op; retained for v4.x compatibility
 FORCE_PROJECT_TREE=false
-ENABLE_SELECTIVE_CONTEXT=false
-MAX_FILES_PER_CONSULTANT=5
+ENABLE_SELECTIVE_CONTEXT=false # Deprecated no-op; retained for v4.x compatibility
+MAX_FILES_PER_CONSULTANT=5     # Deprecated no-op; retained for v4.x compatibility
 
 # =============================================================================
 # REPORTING & STORAGE

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model coverage system that queries up to 10 AI consult
 
 **Self-Exclusion**: The invoking agent is automatically excluded from both the panel and synthesis. Claude Code won't query or synthesize with Claude, Codex CLI won't query or synthesize with Codex, etc.
 
-**Version**: 4.0.3
+**Version**: 5.0.0
 
 ## Distribution
 
@@ -760,6 +760,24 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v5.0.0
+
+- **Coverage claims are now locally auditable instead of resting on synthesis prose.** `scripts/lib/coverage_integrity.sh` normalizes successful structured envelopes into deterministic `<consultant-slug>:<index>` findings, overwriting any provider-supplied IDs. `scripts/synthesize.sh` asks the synthesizer to cite those IDs, then independently compares expected and represented IDs. Missing/duplicate/non-normalizable sources produce `DEGRADED`; unknown IDs and structural failures produce `FAILED`; invented IDs are removed from published coverage. The legacy `coverage`, `weighted_recommendation`, risk, action, and individual-response fields remain present.
+- **Truncation can no longer hide evidence loss.** Coverage/union prompts receive complete atomic findings. Only non-normalizable fallback context is capped, at Unicode code-point boundaries, and local `coverage_input_truncated` / `truncated_consultants` values overwrite model output in normal, local-fallback, and failed-closed artifacts. The report renders status, audited fields, truncation, and the affected consultants. The first Ubuntu CI run exposed an jq-expression compatibility gap; the final form uses jq 1.6-compatible string slicing and passed the release runner.
+- **Presets are host-aware and fail closed.** `get_effective_preset_panel_size` and `select_preset_consultants` preserve the advertised panel after self-exclusion by filling from the canonical roster using static transport evidence only. `max_quality` is ten in the catalog and nine for a canonical host. Insufficient capacity now aborts with promised/selected/missing counts, and health-gate pruning is rechecked before Round 1. Custom agents can satisfy capacity; explicit per-consultant false values remain fallback opt-outs.
+- **Public modes and their documentation have one executable source of truth.** `scripts/public_registry.sh` owns `fast-check -> fast/coverage`, `coverage-review -> balanced/coverage`, `max-coverage -> max_quality/coverage`, every existing preset/alias, and every strategy/default. `scripts/generate_public_docs.sh --check` renders and verifies README, SKILL, and reference tables. CLI conflict/override/unknown diagnostics run before user config, output directories, health checks, or adapters. `doctor --suggest-preset` downgrades to runnable `minimal` when only two effective transports remain.
+- **The v5 release path was exercised end to end within the preregistered cap.** One no-retry `coverage-review` smoke dispatched Gemini, Mistral, and Kimi once each, then synthesized once with Claude: four dispatches total, 3/3 consultant responses, `coverage_integrity=MET` with 12/12 source IDs, and no truncation. The release gate passed 27/27 suites, ShellCheck, Bash 3.2 syntax, generated-doc drift, packaging, and sentinel isolation.
+- **Development safety record.** An early P0.5 mode-registry lookup returned only the mode name, left the preset empty, and caused a local test to invoke ambient adapter auth/capability gates. Gemini/Codex were fixtures; the other adapters returned missing-key/auth/capability diagnostics. The retained transcript does not establish a network/provider request and no successful provider response was observed. The lookup was fixed, all later local release gates used provider/curl sentinels, and the final stub-only mode smoke recorded zero non-fixture adapter calls.
+
+  Deliberately retained: every v4 preset/alias, advanced configuration key, smart routing, custom agents, self-exclusion, and legacy JSON fields. Not claimed: semantic verification that a synthesized sentence faithfully paraphrases the cited atom; v5.0 verifies attribution-set integrity, not natural-language entailment.
+
+### v4.0.4
+
+- **Housekeeping now removes dead implementation without removing public compatibility.** The cleanup deletes uncalled API, cache, optimizer, common, cost, persona, reliability, routing-summary, and session-display helpers, plus the stale README changelog and redundant npm ignore file. The documented `get_routing_mode`, `get_recommended_count`, and `get_category_timeout` helpers stay available and are regression-tested. Six historic config keys that had no runtime reader remain accepted as explicitly deprecated no-ops through v4.x: `SESSION_CLEANUP_DAYS`, `ENABLE_PROGRESS_BARS`, `ENABLE_EARLY_TERMINATION`, `USE_COMPACT_PROMPTS`, `ENABLE_SELECTIVE_CONTEXT`, and `MAX_FILES_PER_CONSULTANT`.
+- **All Bash test suites now share one assertion framework.** `scripts/lib/test_helpers.sh` owns counters, pass/fail/skip rendering, regex/string/numeric/JSON/exit assertions, section rendering, and both concise and detailed summaries. `test_suite.sh` retains compatibility adapters for its established assertion call sites while delegating all mechanics; its summary fails on zero assertions or any failure. The previously excluded `test_functions.sh` is replaced by auto-discovered `test_common.sh`, which keeps regression coverage for diagnosed failures, quorum, health probes, feature-flag recognition, Kimi stream extraction, fenced/bare JSON normalization, confidence preservation, and both detailed-summary failure gates.
+- **The package and active guidance are smaller and truthful.** `package.json#files` is the sole npm allowlist; the package excludes the GitHub release-note archive, tests, fixtures, and maintainer release tooling while retaining active docs. The manifest moves 107 → 61 files, packed bytes 340,662 → 268,831, and unpacked bytes 1,145,406 → 929,330. Setup/CI instructions use `doctor` and `configure`, examples use XDG consultation paths, and routing documentation describes real affinity selection rather than an inert routing-mode/timeout path.
+- **Verification is wholly offline for this patch.** No consultant adapter, model, host transport, roster, cost rate, or synthesis behavior changed, so no billable live smoke was needed. Hermetic `npm test` passed 24/24 suites; core 447 assertions, configure 94 checks, installer/package 51 checks, common-helper 38 checks, Bash 3.2 syntax, ShellCheck, `npm ci --dry-run`, markdown links, and two rounds of cross-family cleanup review are green. PR #16 merged with its merge commit and all final CI checks passed.
+
 ### v4.0.3
 
 - **GLM's active catalog target moves from `glm-5.3` to `glm-5.3-flash` without changing transport or tier semantics.** `scripts/config.sh:189` changes the clean-install default, and the maximum/premium/standard branches at `scripts/config.sh:626-656` select the same exact provider ID. `max_quality` still supplies `GLM_REASONING_EFFORT=max`; economy deliberately remains `glm-4-flash`.

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v4.0.3
+# AI Consultants v5.0.0
 
 > **Coverage, not a single guess.** A panel of up to 10 frontier models from different vendors fans out on your question in parallel and hands you the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses.
 
-[![Version](https://img.shields.io/badge/version-4.0.3-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-5.0.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)
@@ -331,7 +331,7 @@ skillport status ai-consultants
 git clone https://github.com/matteoscurati/ai-consultants.git
 cd ai-consultants
 ./scripts/doctor.sh --fix
-./scripts/setup_wizard.sh
+./bin/ai-consultants configure
 ```
 
 **Commands:**
@@ -455,6 +455,7 @@ Choose the right balance of quality, speed, and cost with model quality tiers.
 
 A preset only chooses the **consultant set and model tier** — every run then fans out in
 parallel and returns the coverage union.
+Preset panels use statically configured transports only (a CLI on `PATH`, or selected API mode with its key). Host self-exclusion is fail-closed; lost canonical slots are filled from `ALL_CONSULTANTS` in canonical order. If the effective target cannot be met, including after an enabled health gate prunes the panel, the run stops with promised/selected/missing-capacity guidance. Configured custom API agents are appended and may satisfy capacity, so a full preset can exceed its advertised count. `max_quality` still advertises 10 consultants, with an effective target of 9 for a canonical invoking host.
 For `max_quality`, Grok, GLM, and DeepSeek are also pinned to their highest
 accepted reasoning effort: Grok Build uses `xhigh`, while GLM and DeepSeek use
 `max`. Unsupported transport capabilities fail explicitly instead of reducing
@@ -468,9 +469,15 @@ likewise receives a 16,384-token completion budget in the maximum tier and a
 provider-specific compact Markdown contract through mmx's native system channel.
 Provider output is tagged `structured`, `fallback`, or `error`;
 malformed/truncated JSON fails
-closed, while usable prose remains available to synthesis with its quality
-disclosed. Synthesis excludes error envelopes and retains bounded response
-detail instead of reducing every consultant to its summary.
+closed. In coverage/union mode, only locally atomized `summary`, `pros`,
+`cons`, `alternatives`, `caveats`, and `references` can be source-attributed;
+fallback prose remains context-only for manual review. `synthesis.json` records
+`coverage_integrity`: `MET` applies only to those audited fields, while
+`DEGRADED`/`FAILED` must not be read as comprehensive coverage. It also records
+locally authoritative `coverage_input_truncated` and `truncated_consultants`:
+only non-normalizable fallback context is capped (at Unicode code-point
+boundaries), never atomic findings; a truncated coverage input is disclosed
+and cannot support a comprehensive coverage claim.
 
 ### Models by Tier
 
@@ -525,39 +532,47 @@ apply_model_tier "economy"   # Set all to economy models
 
 ## Configuration
 
-### Presets
+<!-- ai-consultants:public-registry:start -->
+<!-- ai-consultants:default-synthesis-strategy=coverage -->
+### Public Modes
+
+| Mode | Preset | Default strategy | Use case |
+|---|---|---|---|
+| `fast-check` | `fast` | `coverage` | Fast economy panel for a quick coverage check |
+| `coverage-review` | `balanced` | `coverage` | Balanced panel for a general coverage review |
+| `max-coverage` | `max_quality` | `coverage` | Maximum-quality panel for the broadest coverage |
+
+### Configuration Presets
+
+| Preset | Alias | Target | Tier | Use case |
+|---|---|---:|---|---|
+| `minimal` | — | 2 | base | Quick questions |
+| `balanced` | — | 3 | base | Standard coverage |
+| `thorough` | — | 3 | base | Comprehensive analysis |
+| `high-stakes` | — | 4 | premium | Critical decisions |
+| `security` | — | 3 | base | Security reviews |
+| `cost-capped` | — | 3 | economy | Budget-conscious options |
+| `max_quality` | `max-quality` | 10 | maximum | Maximum coverage for critical decisions |
+| `medium` | — | 3 | standard | General questions |
+| `fast` | — | 2 | economy | Quick checks |
 
-Choose how many consultants to use:
+### Synthesis Strategies
 
-| Preset | Consultants | Tier | Use Case |
-|--------|-------------|------|----------|
-| `max_quality` | All 10 | Maximum + max effort | Critical decisions |
-| `medium` | 3 | Standard | General questions |
-| `fast` | 2 | Economy | Quick checks |
-| `minimal` | 2 (Gemini + Codex) | Default | Quick questions, low cost |
-| `balanced` | 3 (+ Mistral) | Default | Standard consultations |
-| `thorough` | 3 | Default | Comprehensive analysis |
-| `high-stakes` | Expanded panel (4 of 10) | Default | Critical decisions |
-| `security` | Security-focused (3) | Default | Security reviews |
-| `cost-capped` | Budget-conscious | Default | Minimal API costs |
+| Strategy | Description |
+|---|---|
+| `coverage` | Union of every distinct point across the panel **Default** |
+| `compare_only` | Present each consultant side-by-side, without a synthesized union |
+| `majority` | Produce one blended recommendation, weighting all equally |
+| `risk_averse` | Weight conservative responses higher |
+| `security_first` | Prioritize security-focused insights |
+| `cost_capped` | Prefer cheaper consultant opinions within budget |
+<!-- ai-consultants:public-registry:end -->
 
 **Bash:**
 ```bash
 ./scripts/consult_all.sh --preset balanced "Question"
 ```
 
-### Synthesis Strategies
-
-Control how responses are combined:
-
-| Strategy | Description |
-|----------|-------------|
-| `majority` | Most common answer wins (default) |
-| `risk_averse` | Weight conservative responses higher |
-| `security_first` | Prioritize security considerations |
-| `cost_capped` | Prefer simpler, cheaper solutions |
-| `compare_only` | No recommendation, just comparison |
-
 **Bash:**
 ```bash
 ./scripts/consult_all.sh --strategy risk_averse "Question"
@@ -691,22 +706,30 @@ Classify -> Route -> Fan out (parallel) -> Coverage synthesis
 1. **Classify** the question into a category.
 2. **Route** (optional, `ENABLE_SMART_ROUTING`) to the consultants with the best category affinity (`references/affinity.json`).
 3. **Fan out** to every selected consultant in parallel — one shot each, no serial rounds.
-4. **Synthesize** the **coverage union**: the deduplicated set of every distinct point, recommendation, risk, and edge case raised by any consultant. Override with `--strategy compare_only` (side-by-side) or `majority` (a single blended recommendation).
+4. **Synthesize** the **coverage union** over auditable normalized fields. Read
+   `coverage_integrity` before treating it as complete: `MET` means every local
+   atomic source ID is represented once; `DEGRADED` and `FAILED` are explicitly
+   non-comprehensive. Override with `--strategy compare_only` (side-by-side) or
+   `majority` (a single blended recommendation).
 
 ### Output
 
 Each consultation generates:
 
 ```
-/tmp/ai_consultations/TIMESTAMP/
+${XDG_CACHE_HOME:-$HOME/.cache}/ai-consultants/consultations/TIMESTAMP/
+├── context.md            # Built consultation context
 ├── gemini.json          # Individual responses
 ├── codex.json           #   with confidence scores
 ├── mistral.json
 ├── grok.json
-├── synthesis.json       # Coverage union
+├── synthesis.json       # Coverage union plus coverage_integrity/audited_fields
+├── optimization_metrics.json
 └── report.md            # Human-readable report
 ```
 
+The command prints the exact output directory as its final stdout line.
+
 ---
 
 ## Best Practices
@@ -736,7 +759,8 @@ enough — the panel adds little.
 
 - **Never** include credentials or API keys in queries
 - Review and redact sensitive code before sending it to any external consultant
-- Files in `/tmp` are automatically cleaned up
+- Private query and context-staging files are removed automatically; generated
+  reports remain in the XDG cache directory until you remove them
 
 ---
 
@@ -748,121 +772,11 @@ enough — the panel adds little.
 - [Smart Routing](docs/SMART_ROUTING.md) - Category-based routing
 - [JSON Schema](docs/JSON_SCHEMA.md) - Output format specification
 - [Reference Details](references/details.md) - Presets, strategies, best practices
+- [Changelog](https://github.com/matteoscurati/ai-consultants/blob/main/CHANGELOG.md) - Complete version history
 - [Contributing](CONTRIBUTING.md) - How to contribute
 
 ---
 
-## 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`.
-- **Focused 11-consultant roster**: Kilo, Aider, Amp, and Ollama were removed end-to-end, including their adapters and configuration variables. See the [v2.21.1 release note](docs/releases/v2.21.1.md) for migration guidance.
-
-### v2.15.1
-
-- **Gemini fixes (Antigravity CLI)**: the default model (`Gemini 3.1 Pro (High)`) wraps its JSON in a ```` ```json ```` fence; v2.15.0 didn't strip it, so every Gemini reply degraded to a generic fallback. Now de-fenced on all paths (response processing, self-reflection, synthesis).
-- **Works out-of-the-box for `npx`**: Gemini auto-selects API mode when `GEMINI_API_KEY` is set (the `agy` CLI can't be npm-installed and is OAuth-only), so a key-only environment no longer silently drops Gemini.
-- **Synthesis no longer hangs** when `agy` is the synthesizer (it was launched interactively instead of in print mode).
-
-### v2.10.0
-
-- **MiniMax M2.5 support**: New API-based consultant with "The Pragmatic Optimizer" persona
-- **15 consultants total**: Gemini, Codex, Mistral, Kilo, Cursor, Aider, Amp, Kimi, Claude, Qwen3, GLM, Grok, DeepSeek, MiniMax, Ollama
-- **npx distribution**: `npx ai-consultants "question"` - run directly without install
-- **npm packaging**: `package.json` with zero dependencies, `.npmignore` for clean publishing
-
-### v2.8.1
-
-- **Bug fixes**: Fixed `((count++))` abort under `set -e`, missing Amp in consultant map, hardcoded `claude` in synthesize.sh
-- **Security**: Variable name validation before `export` in escalation and cost-aware routing
-- **DRY refactoring**: Rewrote `query_kilo.sh` and `query_cursor.sh` using shared `process_consultant_response()`; added `get_model_for_tier()` as single source of truth
-
-### v2.8.0
-
-- **Amp CLI support**: New consultant with "The Systems Thinker" persona
-- **13 consultants total**: Gemini, Codex, Mistral, Kilo, Cursor, Aider, Amp, Claude, Qwen3, GLM, Grok, DeepSeek, Ollama
-- **Installation**: `curl -fsSL https://ampcode.com/install.sh | bash`
-
-### v2.7.0
-
-- **Qwen CLI support**: CLI/API mode switching for Qwen3 via qwen-code
-- **5 switchable agents**: Gemini, Codex, Claude, Mistral, and now Qwen3 support CLI/API mode
-- **CLI default**: `QWEN3_USE_API` defaults to `false` (CLI mode via qwen-code)
-
-### v2.6.0
-
-- **CLI/API mode switching**: Gemini, Codex, Claude, and Mistral can switch between CLI and API mode
-- **New environment variables**: `*_USE_API` and `*_API_URL` for each switchable agent
-- **Unified API query module**: `lib/api_query.sh` for consistent API handling
-
-### v2.5.0
-
-- **Model quality tiers**: Premium, standard, and economy tiers for all consultants
-- **New presets**: `max_quality`, `medium`, `fast` for quick tier selection
-- **Premium defaults**: All consultants now use premium models by default (March 2026)
-- **`apply_model_tier()` function**: Programmatically switch all models to a tier
-- **Updated models**: opus-4.6, gemini-3.1-pro-preview, gpt-5.3-codex, mistral-large-3, etc.
-
-### v2.4.0
-
-- **Budget enforcement**: Optional budget limits with configurable actions (warn/stop)
-- **Budget checks**: 4 enforcement points (before/after consultation, debate, synthesis)
-- **Budget configuration**: Configurable via natural language or environment variables
-
-### v2.3.0
-
-- **Semantic caching**: Cache responses to avoid redundant API calls (15-25% savings)
-- **Cost-aware routing**: Route simple queries to cheaper models (30-50% savings)
-- **Fallback escalation**: Auto-escalate to premium model if confidence < 7
-- **Debate optimization**: Skip debate if all consultants agree (opt-in)
-- **Category exceptions**: SECURITY/ARCHITECTURE always trigger debate
-- **Quality monitoring**: `optimization_metrics.json` tracks optimization impact
-- **Compact reports**: Shorter reports by default (summaries only)
-- **Response limits**: Per-category token limits (opt-in)
-
-### v2.2.0
-
-- **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/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")
-- **Anonymous peer review**: Unbiased evaluation of responses
-- **Ollama support**: Local model inference for privacy
-- **Panic mode**: Automatic rigor when uncertainty detected
-- **One-liner install**: `curl | bash` installation
-
-### v2.1.0
-
-- New consultants: Aider, DeepSeek
-- 17 configurable personas
-- Token optimization with AST extraction
-
-### v2.0.0
-
-- Persona system with 15 predefined roles
-- Confidence scoring (1-10) on every response
-- Auto-synthesis with weighted recommendations
-- Multi-Agent Debate (MAD)
-- Smart routing by question category
-- Session management and cost tracking
-
----
-
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.

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: 4.0.3
+  version: 5.0.0
 ---
 
-# AI Consultants v4.0.3 - AI Expert Panel
+# AI Consultants v5.0.0 - AI Expert Panel
 
 **Coverage, not a single guess.** Convene a panel of AI "consultants" from different vendors for coding questions: they fan out in parallel and you get the *union* of what they collectively see — the risks, edge cases, and approaches a single model misses. Each consultant has a **configurable persona** that decorrelates its analysis.
 
@@ -115,8 +115,14 @@ Maximum-quality transports use smoke-tested runtime budgets: four advisory
 turns for Mistral/Grok, extended Qwen/DeepSeek timeouts, and larger response
 budgets for reasoning APIs and a compact native-system Markdown contract for
 MiniMax M3. Responses carry an explicit `structured`,
-`fallback`, or `error` quality. Truncated JSON fails closed; usable prose is
-retained and disclosed, and synthesis consumes successful envelopes only.
+`fallback`, or `error` quality. Truncated JSON fails closed. Coverage/union
+synthesis source-attributed claims use only locally normalized atomic fields;
+fallback prose remains visible as context-only manual-review material. Inspect
+`coverage_integrity`: `MET` applies only to its listed `audited_fields`, while
+`DEGRADED` and `FAILED` are never comprehensive coverage claims.
+`synthesis.json` locally records `coverage_input_truncated` and
+`truncated_consultants`; only non-normalizable fallback context can be capped
+(on Unicode code-point boundaries), never normalized atomic findings.
 
 **Self-Exclusion**: The invoking agent is automatically excluded from the panel. When invoked from Claude Code, Claude is excluded; when invoked from Codex CLI, Codex is excluded, etc.
 
@@ -147,7 +153,46 @@ For detailed CLI installation instructions, see [Setup Guide](docs/SETUP.md).
 /ai-consultants:consult "What could go wrong with this design?" src/service.ts
 ```
 
-Presets: `minimal`, `balanced`, `thorough`, `high-stakes`, `security`, `cost-capped`, `max_quality`, `medium`, `fast`. Strategies: `coverage` (default; union of distinct points), `compare_only`, `majority`, `risk_averse`, `security_first`, `cost_capped`. See [Reference Details](references/details.md) for full tables, bash usage, and best practices.
+<!-- ai-consultants:public-registry:start -->
+<!-- ai-consultants:default-synthesis-strategy=coverage -->
+## Public Modes
+
+| Mode | Preset | Default strategy | Use case |
+|---|---|---|---|
+| `fast-check` | `fast` | `coverage` | Fast economy panel for a quick coverage check |
+| `coverage-review` | `balanced` | `coverage` | Balanced panel for a general coverage review |
+| `max-coverage` | `max_quality` | `coverage` | Maximum-quality panel for the broadest coverage |
+
+## Configuration Presets
+
+| Preset | Alias | Target | Tier | Use case |
+|---|---|---:|---|---|
+| `minimal` | — | 2 | base | Quick questions |
+| `balanced` | — | 3 | base | Standard coverage |
+| `thorough` | — | 3 | base | Comprehensive analysis |
+| `high-stakes` | — | 4 | premium | Critical decisions |
+| `security` | — | 3 | base | Security reviews |
+| `cost-capped` | — | 3 | economy | Budget-conscious options |
+| `max_quality` | `max-quality` | 10 | maximum | Maximum coverage for critical decisions |
+| `medium` | — | 3 | standard | General questions |
+| `fast` | — | 2 | economy | Quick checks |
+
+## Synthesis Strategies
+
+| Strategy | Description |
+|---|---|
+| `coverage` | Union of every distinct point across the panel **Default** |
+| `compare_only` | Present each consultant side-by-side, without a synthesized union |
+| `majority` | Produce one blended recommendation, weighting all equally |
+| `risk_averse` | Weight conservative responses higher |
+| `security_first` | Prioritize security-focused insights |
+| `cost_capped` | Prefer cheaper consultant opinions within budget |
+<!-- ai-consultants:public-registry:end -->
+
+Agents may use `--mode` instead of `--preset`; the mode chooses its mapped
+preset and coverage strategy unless an explicit `--strategy` is supplied. See
+[Reference Details](references/details.md) for capacity, fallback, and Bash
+usage details.
 
 ## Workflow
 
@@ -185,13 +230,17 @@ See [Full Configuration Reference](references/configuration.md) for all variable
 ## Output
 
 ```
-/tmp/ai_consultations/TIMESTAMP/
+${XDG_CACHE_HOME:-$HOME/.cache}/ai-consultants/consultations/TIMESTAMP/
+├── context.md          # Built consultation context
 ├── gemini.json        # Individual responses
 ├── codex.json
 ├── synthesis.json     # Coverage union
+├── optimization_metrics.json
 └── report.md          # Human-readable
 ```
 
+The command prints the exact output directory as its final stdout line.
+
 ## Doctor Command
 
 Diagnose and fix issues:

package/bin/ai-consultants

@@ -15,6 +15,17 @@ BIN_DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
 PROJECT_ROOT="$(cd -P "$BIN_DIR/.." && pwd)"
 SCRIPTS_DIR="$PROJECT_ROOT/scripts"
 
+load_public_registry() {
+  # Keep `version` and the lightweight malformed-install diagnostic usable even
+  # when a partial installation lacks the optional public registry file.
+  if [ ! -f "$SCRIPTS_DIR/public_registry.sh" ]; then
+    echo "Error: public registry missing at $SCRIPTS_DIR/public_registry.sh" >&2
+    return 1
+  fi
+  # shellcheck source=../scripts/public_registry.sh
+  source "$SCRIPTS_DIR/public_registry.sh"
+}
+
 # --- Ensure execute permissions (npm can strip them) ---
 ensure_permissions() {
   local needs_fix=false
@@ -47,11 +58,13 @@ case "${1:-}" in
     exit 0
     ;;
   help|--help|-h)
+    load_public_registry || exit 1
     cat <<EOF
 ai-consultants v$VERSION - Cross-vendor AI coverage panel
 
 Usage:
   ai-consultants "question" [files...]        Consult AI experts
+  ai-consultants --mode <name> "question"     Use a public mode
   ai-consultants --preset <name> "question"   Use a configuration preset
   ai-consultants --strategy <name> "question" Use a synthesis strategy
   ai-consultants doctor [--fix] [--json]      Run diagnostics
@@ -62,10 +75,9 @@ Usage:
   ai-consultants version                      Show version
   ai-consultants help                         Show this help
 
-Presets:   minimal, balanced, thorough, high-stakes, security, cost-capped,
-           max_quality, medium, fast
-
-Strategies: coverage, compare_only, majority, risk_averse, security_first, cost_capped
+Modes:      $(registry_mode_rows | cut -d'|' -f1 | tr '\n' ' ' | sed 's/ $//')
+Presets:    $(registry_preset_rows | cut -d'|' -f1 | tr '\n' ' ' | sed 's/ $//')
+Strategies: $(registry_strategy_rows | cut -d'|' -f1 | tr '\n' ' ' | sed 's/ $//')
 
 Examples:
   npx ai-consultants "How to optimize this SQL query?"

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v4.0.3
+# Cost Rates - AI Consultants v5.0.0
 
 This page documents the per-token rates used by the cost tracking system.
 

package/docs/JSON_SCHEMA.md

@@ -1,4 +1,4 @@
-# JSON Schema - AI Consultants v3.5
+# AI Consultants JSON Schema
 
 This document describes the JSON schema used for consultant responses.
 
@@ -22,7 +22,10 @@ The schema is defined in `scripts/lib/schema.json` following JSON Schema Draft-0
     "cons": [...],
     "alternatives": [...],
     "caveats": [...],
-    "references": [...]
+    "references": [...],
+    "findings": [
+      {"id": "gemini:1", "kind": "summary", "field": "summary", "text": "..."}
+    ]
   },
   "confidence": {
     "score": 8,
@@ -61,6 +64,65 @@ The schema is defined in `scripts/lib/schema.json` following JSON Schema Draft-0
 
 ## Optional Fields
 
+### response.findings
+
+`findings` is added locally by the synthesis stage to successful consultant
+responses. It preserves all legacy fields and never trusts provider-supplied
+IDs. Each item has a deterministic local `id` of
+`<consultant-slug>:<one-based-index>`, plus `kind`, source `field`, and the
+atomically attributable `text`. The shared slug rule ASCII-lowercases the
+consultant name, retains `[a-z0-9_]`, replaces other runs with `_`, trims edge
+underscores, and uses `unknown` if empty. Thus the public custom name
+`My_agent` has IDs such as `my_agent:1`.
+
+The conservative normalization contract derives findings only from `summary`,
+`pros`, `cons`, `alternatives`, `caveats`, and `references`; alternatives may
+be meaningful strings or objects with meaningful name/reason text. Empty,
+null, or whitespace alternatives create no finding. Free-form fallback prose
+(`response_quality: fallback`) and successful envelopes with zero atomic
+findings are retained for human review but are non-normalizable; neither can
+be presented as audited coverage. Error envelopes remain excluded from
+synthesis.
+
+## Synthesis Coverage Attribution
+
+Each synthesized `coverage` item requires `source_ids`, containing only local
+IDs from normalized findings. `scripts/lib/schema.json` defines this as
+`definitions.synthesis_coverage_item`; the model prompt requests it, but the
+local post-check is authoritative.
+
+Every synthesis includes `coverage_integrity`:
+
+| Status | Meaning |
+|-------|---------|
+| `MET` | Every expected normalized source ID appears exactly once, with at least one expected ID and no non-normalizable success. It applies only to the audited fields. |
+| `DEGRADED` | A coverage-union source is missing or duplicated, no atomic source exists, or a successful response is non-normalizable. It is never comprehensive. |
+| `FAILED` | Coverage/source attribution is structurally unusable or includes an invented source ID; do not rely on coverage. |
+| `NOT_APPLICABLE` | A non-coverage strategy was selected and no attribution failure was found; it makes no coverage-union claim. |
+
+The object contains `expected_count`, `represented_count`, `missing_ids`,
+`unknown_ids`, `duplicate_ids`, `non_normalizable_consultants`,
+`structural_errors`, `audited_fields`, and `normalization_version`.
+`represented_count` is the count of unique expected IDs actually represented;
+unknown and duplicate IDs cannot inflate it. In coverage/union mode only
+`audited_fields` reach the attributable prompt. Structured `detailed` text and
+fallback prose are not atomized; fallback text is context-only and must never
+produce coverage items or source IDs.
+
+Every synthesis artifact also carries locally authoritative
+`coverage_input_truncated` (boolean) and `truncated_consultants` (a stable,
+first-occurrence-unique array of consultant names discovered in lexically
+ordered response-file order). These fields overwrite any values supplied by a
+model and are present even on local fallback or failed-closed artifacts.
+`SYNTH_DETAIL_MAX_CHARS` applies only to usable, non-normalizable fallback
+context, never to normalized finding text. Its unit is Unicode code points:
+input with exactly the limit is retained and does not set the flag; only input
+with more code points is shortened to that limit, preserving complete
+multibyte UTF-8 characters. When such context is truncated, coverage/union is
+at least `DEGRADED` and its disclosure names the affected consultants; it is
+never a comprehensive claim. A non-coverage strategy can remain
+`NOT_APPLICABLE`, but still exposes this metadata and disclosure.
+
 ### response.code_snippets
 
 Array of code snippets: