ai-consultants 2.10.8 → 2.14.1

package/.claude/commands/ai-consultants:consult.md

@@ -14,26 +14,28 @@ Query multiple AI models for expert opinions on a coding question.
 
 1. If no question provided in $ARGUMENTS, ask the user what they want to consult about.
 
-2. **File context handling**: Check if $ARGUMENTS contains file paths (tokens containing `/` or extensions like `.ts`, `.js`, `.py`, `.sh`, `.json`, `.yaml`, `.yml`, `.md`, `.go`, `.rs`, `.java`, `.rb`, `.css`, `.html`, `.tsx`, `.jsx`, `.c`, `.cpp`, `.h`).
-   If file paths are found:
-   - Extract each file path token from $ARGUMENTS
-   - Read each file using the **Read** tool
-   - Build an enriched query by replacing file path tokens with their inline contents:
-     ```
-     <original question text without file paths>
+2. **File context handling**: Identify which strings in $ARGUMENTS refer to files the user wants the consultants to look at. Use your judgment — verify existence via `Glob` or `Bash ls` when uncertain. This replaces fragile regex detection: a `Makefile`, `Dockerfile`, dotfile, or path without a common extension is still a file; an URL or regex pattern in the question text is not.
 
-     --- File: path/to/file.ts ---
-     <file contents>
-     --- End File ---
-     ```
-   - Use this enriched query in step 3 instead of raw $ARGUMENTS
+   For each file you identify:
+   - Strip the file path from the question text.
+   - Decide its relevance tag: `PRIMARY` (the focus of the question — what the consultants should critique) or `CONTEXT` (ambient reference — the consultants should read but not necessarily critique). Default to `PRIMARY` if every referenced file is central.
+   - Pass each path as a positional argument to `consult_all.sh` with the syntax `path/to/file@TAG` (omit `@TAG` to default to `PRIMARY`).
+
+   **Do not inline file contents into the query string.** `build_context.sh` reads files directly from the filesystem and runs the AST optimization pipeline — passing file paths as arguments is what enables it. Inlining defeats the optimization and inflates the consultants' context.
+
+   **Note (Claude only):** Do not use your `Read` tool to dump file contents into the query. `build_context.sh` handles file reading itself, without the `N\t` line-number prefix that `Read` adds.
 
 3. **Run the consultation**:
    ```bash
-   cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ./scripts/consult_all.sh '<query>'
+   cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ./scripts/consult_all.sh '<question>' <file1[@TAG]> <file2[@TAG]> ...
    ```
-   Replace `<query>` with the enriched query from step 2 (or $ARGUMENTS if no files were detected). Use single quotes around the query to prevent shell expansion of special characters.
-   **Capture the last line of stdout** — it contains the output directory path (e.g., `/tmp/ai_consultations/20260315_143022_12345/`).
+   - `<question>` is the question text with file paths stripped. Use single quotes to prevent shell expansion.
+   - Each `<fileN>` is a file path, optionally suffixed with `@PRIMARY` or `@CONTEXT`.
+   - **If the question text exceeds ~8KB or contains awkward quoting**, write it to a tmpfile and use `--query-file <path>` instead:
+     ```bash
+     cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ./scripts/consult_all.sh --query-file /tmp/question.txt <file1[@TAG]> ...
+     ```
+   - **Capture the last line of stdout** — it contains the output directory path (e.g., `/tmp/ai_consultations/20260315_143022_12345/`).
 
 4. **Read the results** from the output directory captured in step 3:
    - Read `<output_dir>/report.md` using the **Read** tool
@@ -85,6 +87,7 @@ Query multiple AI models for expert opinions on a coding question.
 | `ENABLE_DEBATE=true` | Enable multi-round debate for deeper analysis |
 | `ENABLE_SMART_ROUTING=true` | Auto-select best consultants for the question type |
 | `DEBATE_ROUNDS=2` | Number of debate rounds (1-3) |
+| `FORCE_PROJECT_TREE=true` | Include the project tree even for pointed categories (SECURITY, QUICK_SYNTAX, etc.) |
 
 ## Follow-up
 

package/.claude/commands/ai-consultants:debate.md

@@ -21,26 +21,25 @@ Run a multi-round debate where AI consultants critique each other's responses an
 
 1. If no question provided in $ARGUMENTS, ask the user what they want to debate.
 
-2. **File context handling**: Check if $ARGUMENTS contains file paths (tokens containing `/` or extensions like `.ts`, `.js`, `.py`, `.sh`, `.json`, `.yaml`, `.yml`, `.md`, `.go`, `.rs`, `.java`, `.rb`, `.css`, `.html`, `.tsx`, `.jsx`, `.c`, `.cpp`, `.h`).
-   If file paths are found:
-   - Extract each file path token from $ARGUMENTS
-   - Read each file using the **Read** tool
-   - Build an enriched query by replacing file path tokens with their inline contents:
-     ```
-     <original question text without file paths>
+2. **File context handling**: Identify which strings in $ARGUMENTS refer to files the user wants the consultants to debate over. Use your judgment — verify existence via `Glob` or `Bash ls` when uncertain. A `Makefile`, `Dockerfile`, dotfile, or path without a common extension is still a file; an URL or regex pattern in the question text is not.
 
-     --- File: path/to/file.ts ---
-     <file contents>
-     --- End File ---
-     ```
-   - Use this enriched query in step 3 instead of raw $ARGUMENTS
+   For each file you identify:
+   - Strip the file path from the question text.
+   - Decide its relevance tag: `PRIMARY` (the focus of the debate — what the consultants should critique) or `CONTEXT` (ambient reference — read but not necessarily critiqued). Default to `PRIMARY` if every referenced file is central.
+   - Pass each path as a positional argument to `consult_all.sh` with the syntax `path/to/file@TAG` (omit `@TAG` to default to `PRIMARY`).
+
+   **Do not inline file contents into the query string.** `build_context.sh` reads files directly from the filesystem and runs the AST optimization pipeline.
+
+   **Note (Claude only):** Do not use your `Read` tool to dump file contents into the query. `build_context.sh` handles file reading itself, without the `N\t` line-number prefix that `Read` adds.
 
 3. **Run the debate consultation**:
    ```bash
-   cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ENABLE_DEBATE=true DEBATE_ROUNDS="${DEBATE_ROUNDS:-2}" ./scripts/consult_all.sh '<query>'
+   cd "${AI_CONSULTANTS_DIR:-$HOME/.claude/skills/ai-consultants}" && INVOKING_AGENT=claude ENABLE_DEBATE=true DEBATE_ROUNDS="${DEBATE_ROUNDS:-2}" ./scripts/consult_all.sh '<question>' <file1[@TAG]> <file2[@TAG]> ...
    ```
-   Replace `<query>` with the enriched query from step 2 (or $ARGUMENTS if no files were detected). Use single quotes around the query to prevent shell expansion of special characters.
-   **Capture the last line of stdout** — it contains the output directory path.
+   - `<question>` is the question text with file paths stripped. Use single quotes to prevent shell expansion.
+   - Each `<fileN>` is a file path, optionally suffixed with `@PRIMARY` or `@CONTEXT`.
+   - **If the question text exceeds ~8KB or contains awkward quoting**, write it to a tmpfile and pass `--query-file <path>` instead of the inline question.
+   - **Capture the last line of stdout** — it contains the output directory path.
 
 4. **Read the results** from the output directory captured in step 3:
    - Read `<output_dir>/report.md` using the **Read** tool

package/CLAUDE.md

@@ -6,7 +6,7 @@ AI Consultants is a multi-model AI deliberation system that queries up to 15 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.10.8
+**Version**: 2.14.1
 
 ## Distribution
 
@@ -47,7 +47,7 @@ ai-consultants/
 │   ├── debate_round.sh         # Multi-Agent Debate
 │   ├── classify_question.sh    # Question classifier
 │   ├── followup.sh             # Follow-up queries
-│   ├── preflight_check.sh      # Health check
+│   ├── preflight_check.sh      # DEPRECATED v2.10.9 (thin wrapper -> doctor.sh)
 │   └── lib/
 │       ├── common.sh           # Shared utilities (logging, panic mode)
 │       ├── personas.sh         # Consultant persona definitions
@@ -732,16 +732,36 @@ For detailed information, see:
 
 Use [Conventional Commits](https://www.conventionalcommits.org/): `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`, `test:`, `perf:`, `ci:`. Scope is optional (e.g., `feat(routing): add fallback escalation`).
 
+### Pre-commit hook (v2.14.1+)
+
+A git pre-commit hook runs `shellcheck` on staged `.sh` files using the exact CI invocation. Install it once per checkout:
+
+```bash
+npm run install-hooks    # copies scripts/hooks/pre-commit into .git/hooks/
+```
+
+Manual lint of the full repo: `npm run lint`. Bypass the hook: `git commit --no-verify` (use sparingly — CI will catch the same warnings).
+
 ## Release Process
 
 Every version bump **must** include a release note in `docs/releases/v<VERSION>.md`. Use the template below.
 
 ### Steps
 
-1. Update version in all files: `package.json`, `SKILL.md` (frontmatter + title), `README.md` (title + badge), `CLAUDE.md` (`**Version**`), `docs/cost_rates.json`, `docs/COST_RATES.md` (title)
-2. Add changelog entry in CLAUDE.md under `## Changelog`
-3. Create `docs/releases/v<VERSION>.md` using the template below
-4. Commit, push, and optionally create a GitHub release pointing to the release note
+1. **Update version** in all files: `package.json`, `scripts/config.sh` (`AI_CONSULTANTS_VERSION`), `SKILL.md` (frontmatter + title), `README.md` (title + badge), `CLAUDE.md` (`**Version**`), `docs/cost_rates.json`, `docs/COST_RATES.md` (title)
+2. **Add `## Changelog` entry** in CLAUDE.md (developer-facing, long-form, rationale + line-level commentary)
+3. **Add `CHANGELOG.md` entry** at the top of `CHANGELOG.md` (Keep a Changelog format: `## [VERSION] - YYYY-MM-DD` with `### Added/Changed/Fixed/Removed/Deprecated/Security` subsections — user-facing, one-line bullets)
+4. **Create `docs/releases/v<VERSION>.md`** using the template below (highlights + upgrade guide — for GitHub releases / users)
+5. **Update workspace sync surfaces** if applicable: `aiconsultants.sh/index.html` (`softwareVersion` schema + badge), `../CLAUDE.md` workspace guide ("Latest at time of last sync" + Recent release line)
+6. **Run tests**: `npm test` must pass before committing
+7. **Commit, push**, and optionally create a GitHub release pointing to the release note
+
+**Why three changelog surfaces?** They serve different audiences:
+- `CLAUDE.md ## Changelog` — what the *next maintainer* needs (file/line references, rationale, latent bugs uncovered)
+- `CHANGELOG.md` — what *users on a specific version* need (concise, categorized, scannable)
+- `docs/releases/v<VERSION>.md` — what *people deciding to upgrade* need (highlights, breaking changes, upgrade guide)
+
+Drift between these is the most common release-process bug. Keep them in sync per release.
 
 ### Release Note Template
 
@@ -802,6 +822,101 @@ curl -fsSL https://raw.githubusercontent.com/matteoscurati/ai-consultants/main/s
 
 ## Changelog
 
+### v2.14.1
+- **Pre-commit hook**: `scripts/hooks/pre-commit` runs `shellcheck` on staged `.sh` files under `scripts/` using the exact CI invocation (`-S warning -x -e SC1091,SC1090,SC2034,SC2155`). Mirrors `.github/workflows/ci.yml:32` so the same warnings that fail CI also fail the local commit. Filtered with the regex `^scripts/(lib/)?[^/]+\.sh$` to match the CI glob exactly (test fixtures under `scripts/test_fixtures/` are correctly excluded). Bypass: `git commit --no-verify`.
+- **`scripts/install-hooks.sh`**: idempotent installer wired to `npm run install-hooks`. Backs up any existing different hook to `.git/hooks/pre-commit.backup.<timestamp>` to avoid clobbering contributor customizations (`FORCE=1` skips backup). Silent no-op outside a git checkout, so it's safe to wire to npm `prepare` or similar lifecycle hooks if ever needed.
+- **`npm run lint`**: convenience wrapper for the full-repo shellcheck invocation. Useful pre-push when you want to validate without staging.
+- **Motivation**: v2.14.0 push to `main` failed CI due to SC2164 in `scripts/test_context_optimization.sh:18` (`cd "$PROJECT_ROOT"` lacked `|| exit`). The new script passed `bash -n` locally but `bash -n` is purely a parser check — it doesn't run any linter. The pre-commit hook closes that gap. Documented in `CONTRIBUTING.md` Development Environment Setup section and briefly in `## Git Conventions` here.
+- **No runtime behavior change**: this is contributor-only tooling. Tests still pass (7 suites, ~510 assertions).
+
+### v2.14.0
+- **Context handoff: AST optimization pipeline now engages on the primary slash-command path**. Pre-fix, `/ai-consultants:consult` instructed the invoking agent (Claude/Codex/Gemini) to inline file contents into the query string, which meant `build_context.sh` ran with zero `FILES` and the entire `lib/code_optimizer.sh` + `lib/chunking.sh` + `lib/symbol_map.sh` stack was dead code. The three `.{claude,codex,gemini}/commands/ai-consultants:{consult,debate}.md` slash commands now instruct agents to pass file paths as positional arguments to `consult_all.sh`; `build_context.sh` does the file reading and runs the optimizer.
+- **`build_context.sh` reads exported `QUESTION_CATEGORY`** to decide whether to include the project tree section. SECURITY, QUICK_SYNTAX, ALGORITHM, BUG_DEBUG, DATABASE, TESTING categories skip it (noise for pointed questions); ARCHITECTURE, CODE_REVIEW, API_DESIGN, GENERAL include it; unknown categories default to "include" (conservative). New env var `FORCE_PROJECT_TREE=true` bypasses the heuristic. Categories source: `classify_question.sh` already exports `QUESTION_CATEGORY` in `consult_all.sh:241-242` — zero new code path, just consumes existing signal.
+- **File relevance tags**: `path/to/file@PRIMARY` (focus of the question) vs `path/to/file@CONTEXT` (ambient reference). Default `PRIMARY` when omitted. Unknown tags fall back to PRIMARY with a `log_warn`. New parallel `FILE_TAGS` array in `build_context.sh`. Rendered as `### File: \`path\` (TAG)` in the `## Relevant Files` section, with a header explaining the two values to consultants. Downstream synthesis/debate/peer_review unaffected (they don't read `context.md`).
+- **`--query-file <path>` flag in `consult_all.sh`** as escape hatch for queries exceeding shell ARG_MAX (~256KB on macOS) or containing mixed-quote payloads. Conflicts with positional question arg (parser-level error). Validates file existence at parse time.
+- **Slash-command file detection**: replaced the hardcoded extension regex + `/`-in-token heuristic with "use your judgment, verify via Glob/Bash when uncertain". Pre-fix missed `Makefile`, `Dockerfile`, dotfiles; false-positive on URLs and regex patterns in question text. The invoking agent has full conversation context so it's better placed than a regex.
+- **Claude-only note in `.claude/commands/ai-consultants:consult.md`**: explicit instruction not to use `Read` tool output (which carries `N\t` line-number prefix) since `build_context.sh` reads files itself. Codex and Gemini variants don't carry this note (their tools don't add the prefix).
+- **First test coverage for `lib/code_optimizer.sh` and `lib/chunking.sh`**: new `scripts/test_context_optimization.sh` (17 assertions, 14 tests). Covers: @TAG default/explicit/unknown, QUESTION_CATEGORY routing (SECURITY drops, ARCHITECTURE keeps, unknown includes), FORCE_PROJECT_TREE override, Python AST extraction over MAX_CONTEXT_FILE_BYTES threshold, `optimize_code_file` smoke, `chunk_file_semantically` JSON shape, --query-file parsing (valid/missing/conflict), legacy no-FILES path preservation. Picked up automatically by `test_all.sh`'s `find`-based discovery — no manual wire-up needed. Total: 7 suites, ~510 assertions.
+- **Test fixtures**: new `scripts/test_fixtures/context/` with `sample.py` (Python class + methods + main), `sample.sh` (Bash with functions), `sample.json` (config), `sample.txt` (plain text). Deterministic, no timestamps or randomness.
+- **Help text updates**: `consult_all.sh --help` documents `--query-file` and `@TAG` syntax; `build_context.sh` usage error documents `QUESTION_CATEGORY` and `FORCE_PROJECT_TREE`.
+- **Known gap surfaced**: `_supports_ast_extraction` declares 13 languages (Python, JS, TS, Go, Rust, Java, C++, C, C#, Ruby, PHP, Swift) but `lib/code_optimizer.sh` has dedicated extractors for only 4 (Python, JS/TS, Bash, Go); the other 9 fall back to `_extract_generic` (grep-based). Documented in release note; tracked for future tree-sitter-backed extraction.
+- **Backwards compat**: agents that still inline file contents into the query (pinned old slash commands) keep working — `build_context.sh` degrades to no-FILES branch, just without the optimization benefit. Direct bash users of `./scripts/consult_all.sh "q" file1 file2` get the same behavior plus the new optimization.
+
+### v2.13.1
+- **Perf**: XDG roots resolved once at first `config.sh` source and **exported** as `_AI_CONSULTANTS_XDG_{CACHE,STATE,DATA}` — child query subshells inherit the values and skip ~6 subshells/child × 14 children = ~84 forks per consultation (~200-400ms saving on macOS).
+- **Perf**: `apply_launch_stagger()` switched from `awk "BEGIN{printf}"` to pure-bash `printf '%d.%03d'` — 14 forks eliminated per consultation (~50-70ms aggregate).
+- **Perf/DRY**: `_count_available_consultants` entries pre-uppercased (`"GEMINI|ENABLE_GEMINI|gemini"`) — 15 `to_upper` subshells eliminated per `--suggest-preset` invocation. Also fixes the latent self-exclusion case-mismatch the round-2 review caught.
+- **Latent bug fix**: 5 `lib/*.sh` files (`cache.sh`, `session.sh`, `api.sh`, `chunking.sh`, `costs.sh`) had hardcoded `/tmp/...` defaults that drifted from the v2.13 XDG migration. Their fallbacks now reference `${_AI_CONSULTANTS_XDG_*}` so they stay aligned even if sourced standalone (e.g. from a future test). `lib/session.sh::cleanup_old_sessions` no longer hardcodes `/tmp/ai_consultations` either — uses `$DEFAULT_OUTPUT_DIR_BASE`.
+- **DRY**: extracted `scripts/lib/test_helpers.sh` (~80 LOC) — `assert_eq`, `assert_match`, `run_test`, `test_summary`, `_reset_state` hook. Eliminates the ~90 LOC of triplication across `test_user_config.sh`, `test_doctor.sh`, `test_bin.sh`. Future test suites just `source lib/test_helpers.sh`.
+- **CI**: `scripts/test_all.sh` (master runner introduced post-v2.13.0) now also includes `test_suite.sh` — adds 258 library assertions to `npm test`, closing the "tests on disk but not gating CI" gap. Total: 6 suites, ~493 assertions.
+- **Style**: 37 → 0 shellcheck warnings under the project exclusions (`-e SC2034,SC2086,SC1091,SC2155,SC2154`). Touches: `configure.sh` (26 SC2004 + 1 SC2129), `lib/routing.sh` (4 SC2004/2321), `lib/code_optimizer.sh` (2 SC2001 sed → param expansion), `lib/chunking.sh` (2 SC2001), `lib/voting.sh` (1 SC2126), `lib/common.sh` (1 SC2005, 1 SC2317 annotated), `lib/api_query.sh` (1 SC2317 annotated), `lib/symbol_map.sh` (2 SC1090 annotated), `config.sh` (1 SC2317 annotated), `test_set_e_safety.sh` (1 SC2001 annotated).
+- **Code quality**: `consult_all.sh` `_MODEL` var resolution switched from inline `tr` to `to_upper()` helper for consistency. Stale `name_upper` variable in `_count_available_consultants` renamed to `name`. `find_user_config_file` redundant `|| echo ""` simplified to `|| true`.
+- All 6 test suites pass (493 assertions). Zero behavioral change for end users; XDG cache export is the only new env-var contract.
+
+### v2.13.0
+- New `doctor --suggest-preset --question "..."` recommends a preset + strategy combo for a question, based on category classification (`classify_question.sh`) and the count of available consultants (gated by `ENABLE_*` flags and self-exclusion). Outputs a one-line `ai-consultants` command + reasoning, or structured JSON via `--json` for tooling/automation.
+- Classifier failures now surface explicitly as `Warning: classification of your question failed` (with the underlying error). Pre-fix the failure was masked by `2>/dev/null` and silently degraded to `GENERAL`.
+- `--suggest-preset` short-circuits to "install more CLIs" hint when fewer than 2 consultants are usable — previously could recommend e.g. `minimal` preset with 0 consultants.
+- `_count_available_consultants()` now respects `ENABLE_*` flags and subtracts the invoking agent (self-exclusion). Pre-fix the count included disabled consultants, leading `_recommend_combo` boundaries to fire on a phantom panel size.
+- `ENABLE_DEBATE_OPTIMIZATION` promoted from opt-in to default `true` based on operator experience over 4 stable releases — debate is auto-skipped when confidence spread < `DEBATE_CONFIDENCE_SPREAD_THRESHOLD` (default 2). SECURITY and ARCHITECTURE remain mandatory-debate. No empirical benchmark in-tree yet; tracked for v2.14.
+- XDG Base Directory compliance for transient and persistent paths (per freedesktop.org spec):
+  - `DEFAULT_OUTPUT_DIR_BASE`: `/tmp/ai_consultations` → `$XDG_CACHE_HOME/ai-consultants/consultations` (typically `~/.cache/...`)
+  - `CACHE_DIR`: `/tmp/ai_consultants_cache` → `$XDG_CACHE_HOME/ai-consultants/cache`
+  - `RATE_LIMIT_DIR`, `CHUNK_TEMP_DIR`: `/tmp/ai_consultants_*` → `$XDG_CACHE_HOME/ai-consultants/{ratelimit,chunks}`
+  - `SESSION_DIR`: `/tmp/ai_consultants_sessions` → `$XDG_STATE_HOME/ai-consultants/sessions` (`~/.local/state/...`)
+  - `COST_TRACKING_FILE`: `/tmp/ai_consultants_costs.json` → `$XDG_DATA_HOME/ai-consultants/costs.json` (`~/.local/share/...`)
+  - All env vars still respected; restore old behavior with `export DEFAULT_OUTPUT_DIR_BASE=/tmp/ai_consultations` etc.
+- New `lib/user_config.sh::get_xdg_dir()` helper — single source of truth for XDG resolution; falls back to `$HOME/.{cache,local/state,local/share}` then `/tmp/ai-consultants-{kind}` for distroless containers.
+- README slimmed: env-var section now points to `references/configuration.md` for the full ~150-var list and recommends `ai-consultants init` as the primary onboarding path.
+- `RATE_LIMIT_DIR` and `CHUNK_TEMP_DIR` lifted to `config.sh` for consistency (were lib-only defaults).
+- `config.sh` now hard-fails with `FATAL: ... get_xdg_dir()` if `lib/user_config.sh` is missing — pre-fix the v2.13 XDG defaults silently regressed to `/tmp/ai_consultants/...` when the helper was absent (corrupt install, refactor regression).
+- New `scripts/test_doctor.sh` — 25 assertions in 12 tests: `--suggest-preset` across categories (SECURITY, QUICK_SYNTAX, ARCHITECTURE, ALGORITHM, GENERAL), no-question default, long-question truncation, short-circuit behavior, **+ review fixes**: `--json` output schema, count<2 install hint, classifier failure warning, `config.sh` FATAL on missing helper, count respects ENABLE_* flags.
+- `scripts/test_user_config.sh` extended to 38 assertions in 18 tests — added: `get_xdg_dir` cache/state/data resolution, fallback to `~/.{cache,local/state,local/share}`, distroless `/tmp/ai-consultants-*` fallback, invalid kind handling, `config.sh` XDG path defaults, explicit env var override precedence, `ENABLE_DEBATE_OPTIMIZATION=true` default assertion.
+- Round-2 review fix: `_count_available_consultants` self-exclusion was dead code due to UPPERCASE vs MixedCase mismatch — counter compared `Claude` to `get_self_consultant_name`'s `CLAUDE`. Now uppercases the entry name via `to_upper`; `INVOKING_AGENT` correctly drops 1 from the count. Regression test added.
+- Round-2 fix: `--suggest-preset --json` pre-flights `jq` with a clear error message instead of aborting under `set -e` with `command not found` (the main `check_dependencies` jq probe doesn't run when `--suggest-preset` short-circuits).
+- Round-2 fix: `--json` schema gains `schema_version: 1` and `recommended_command` fields — tooling no longer has to reconstruct the invocation client-side and has a signal for future schema evolution.
+- Round-2 fix: `_count_available_consultants` no longer hardcodes a "default-true" list that drifted from `config.sh` (claimed Aider default-true; actually false). Removed; relies solely on `config.sh` defaults via `${!flag:-false}`.
+- New `scripts/test_all.sh` master runner aggregates all 5 standalone test suites; `npm test` wired in `package.json`. Closes the "tests on disk but not gating CI" gap from v2.11/v2.12 review carryovers.
+- `scripts/test_doctor.sh` extended to 31 assertions: + self-exclusion regression, + jq preflight, + schema_version/recommended_command shape.
+
+### v2.12.0
+- New persistent user-config dir at `~/.config/ai-consultants/` (XDG-compliant; honors `AI_CONSULTANTS_CONFIG_DIR` and `XDG_CONFIG_HOME`)
+- New `lib/user_config.sh` with `load_user_config()` — sourced from `config.sh` at the very top, before any defaults are applied
+- `load_user_config` is **idempotent** via a process-wide guard `_AI_CONSULTANTS_USER_CONFIG_LOADED` — `config.sh` is sourced 15-30 times per consultation transitively, and without the guard non-idempotent user config (PATH appends, counters, log appends) would compound silently
+- `.env` (KEY=value) and `config.sh` (full bash) both supported; existing env vars always win over user config (precedence: CLI > env > user config > defaults > hardcoded)
+- `.env` parser **strips trailing CR** so Windows CR-LF line endings don't silently corrupt values (`ENABLE_DEBATE=true\r` would otherwise break every `[[ "$X" == "true" ]]` comparison downstream)
+- New `ai-consultants init [--force]` subcommand scaffolds the user config dir with `.env` (copied from `.env.example`, chmod 600) and `config.sh` (minimal sourceable template); refuses to scaffold into a symlinked dir (root + hostile symlink protection); pre-flights write permission with a friendly error pointing to `AI_CONSULTANTS_CONFIG_DIR`
+- `bin/ai-consultants` no longer hardcodes the version (was stuck at 2.10.0 since v2.10.0 release); reads `AI_CONSULTANTS_VERSION` from `scripts/config.sh` and **validates it as semver** — falls back to `vunknown` instead of `vAI_CONSULTANTS_VERSION=2.12.0` when the parse fails
+- `get_user_config_dir` returns empty + exit 1 when both `HOME` and `XDG_CONFIG_HOME` are unset (e.g. distroless container) instead of computing the broken path `/.config/ai-consultants`; callers (`doctor.sh`, `bin/init`) handle this with a clear error
+- Single source of truth for user-dir resolution: `lib/user_config.sh::get_user_config_dir()`; `routing.sh`, `doctor.sh`, and `bin/ai-consultants` now all source it instead of duplicating the precedence ladder (was DRY-violated 4x)
+- `lib/routing.sh::_load_affinity_data` extended with search path: `AFFINITY_FILE` env > `~/.config/ai-consultants/affinity.json` > bundled default — drops a custom matrix in the user dir without setting any env var
+- `doctor.sh` adds `check_user_config()` reporting dir presence, files loaded, and warns on `.env` lax permissions — total checks now 22
+- New regression test `scripts/test_user_config.sh` — 20 assertions in 11 tests: .env loading + quote stripping, env precedence, edge cases (comments/blanks/`export`/quoted/indented), invalid keys, config.sh ordering, XDG fallback, missing-files silence (now also asserts no stderr output), AI_CONSULTANTS_CONFIG_DIR priority, **CR-LF stripping**, **idempotency guard**, **HOME-unset fallback**
+- New `scripts/test_bin.sh` — 10 assertions in 8 tests covering `bin/ai-consultants version` (matches config.sh, semver-shaped, fallback to "unknown" on malformed config) and `init` (chmod 600 enforcement, both files created, idempotent without --force, --force overwrites, refuses symlinked dir)
+- `scripts/test_routing_parity.sh` extended to 146 assertions (added user-dir branch of `_resolve_affinity_path`)
+
+### v2.11.0
+- Externalized routing affinity matrix from nested `case` statements in `lib/routing.sh` to `references/affinity.json` (~190 lines of bash → 60 lines of JSON)
+- Custom matrix at runtime via `AFFINITY_FILE=/path/to/custom.json` (e.g. tweak scores per project, disable consultants by category)
+- `get_affinity()` now performs JSON lookup with two-level cache: file content cached on first read, per-(category, consultant) result cached after first lookup
+- Cache uses leading-space delimiter to prevent substring collisions (e.g. `DEBUG|X=` would have falsely matched a cached `BUG_DEBUG|X=10` — caught in review pass before release)
+- `doctor.sh` adds 3 new checks for affinity: file presence, JSON schema validity, coverage (every consultant in every category) — total checks now 21
+- Golden parity test in `scripts/test_routing_parity.sh`: 144 assertions covering all 9 categories × 14 consultants + edge cases (unknown consultant, unknown category, AFFINITY_FILE override, cache auto-invalidation, cache substring-collision regression)
+- `docs/SMART_ROUTING.md` rewritten: removed stale per-consultant table (was out of sync with code since v2.8/v2.9/v2.10 added Amp, Kimi, MiniMax), now points to JSON as source of truth and documents schema + override
+- `references/affinity.json` `_comment` documents the asymmetric 3-tier fallback (unknown consultant → 5, unknown category → 8, missing cell → 5) and the rationale
+- Bug class regression test in `scripts/test_set_e_safety.sh`: static lint covers `((var++))` AND `((var--))` AND `let var++` family, plus dynamic check on bash 4+ for the abort pattern fixed in v2.8.1, v2.10.1, v2.10.9
+- `consult_all.sh` ENABLE_PREFLIGHT path no longer swallows doctor output — the diagnostic is now captured to a tmpfile and dumped on failure (previously `>/dev/null 2>&1` repeated the original preflight silent-failure bug)
+- Cleaned `((attempt++)) || true || true` artifacts in `lib/api.sh` (introduced by the v2.10.9 mechanical sweep on lines that were already protected)
+
+### v2.10.9
+- Fixed silent failure of `preflight_check.sh` under `set -euo pipefail`: helper functions like `check_cli_installed` returned non-zero on missing CLIs, and call sites lacked `|| true` — the script aborted after "Checking CLI installations..." with no diagnostic output
+- Deprecated `preflight_check.sh` in favor of `doctor.sh` (stale v2.0 script covering only 6/15 consultants and missing CLI/API mode checks); `preflight_check.sh` is now a thin wrapper that prints a deprecation warning and execs `doctor.sh "$@"`
+- Ported `--suggest-config` from preflight to `doctor.sh`, expanded coverage from 6 to 15 consultants (now also detects API-only consultants via API key presence)
+- Added `--quick` flag to `doctor.sh` (accepted as no-op for backward compat with preflight)
+- Updated `consult_all.sh` ENABLE_PREFLIGHT path to invoke `doctor.sh` directly
+- Defensive sweep: protected 15 latent `((var++))` increments across `peer_review.sh`, `setup_wizard.sh`, `test_functions.sh`, `lib/api.sh`, `lib/common.sh`, `lib/reflection.sh`, and `doctor.sh` with `|| true` (matches v2.8.1/v2.10.1 codebase convention; latent because bash 3.2 doesn't abort but bash 4+ does)
+- Fixed real shellcheck warnings: SC2059 unsafe printf format string in `lib/progress.sh`, SC2012 `ls | wc -l` race in `install.sh` (replaced with `find`), SC2329 false positive in `query_ollama.sh` cleanup trap (annotated), SC2016 intentional sed pattern in `peer_review.sh` (annotated)
+
 ### v2.10.8
 - Fixed `docs/cost_rates.json` drift introduced by v2.10.6: `consultant_fallbacks` (used at runtime by `lib/costs.sh`) and `model_tiers` were still pointing at the old IDs (`opus-4.6`, `gpt-5.3-codex`, `composer-1.5`, `deepseek-reasoner`, `sonnet-4.6`, `haiku-4.5`)
 - Added price entries for the v2.10.6 model IDs: `claude-opus-4-7`, `claude-sonnet-4-6`, `claude-haiku-4-5`, `gpt-5.5`, `composer-2`, `deepseek-v4-pro`, `nvidia/nemotron-3-super-120b-a12b:free`

package/README.md

@@ -1,8 +1,8 @@
-# AI Consultants v2.10.8
+# AI Consultants v2.14.1
 
 > Query multiple AI models simultaneously for expert opinions on coding questions. Get diverse perspectives, automatic synthesis, confidence-weighted recommendations, and multi-agent debate.
 
-[![Version](https://img.shields.io/badge/version-2.10.8-blue.svg)](https://github.com/matteoscurati/ai-consultants)
+[![Version](https://img.shields.io/badge/version-2.14.1-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)
@@ -548,39 +548,35 @@ Control how responses are combined:
 
 ### Environment Variables
 
-```bash
-# Core features
-ENABLE_DEBATE=true           # Multi-agent debate
-ENABLE_SYNTHESIS=true        # Automatic synthesis
-ENABLE_SMART_ROUTING=true    # Intelligent consultant selection
-ENABLE_PANIC_MODE=auto       # Automatic rigor for uncertainty
-
-# Defaults
-DEFAULT_PRESET=balanced      # Preset when --preset not given
-DEFAULT_STRATEGY=majority    # Strategy when --strategy not given
+**Most users only need:**
 
-# Ollama (local models)
-ENABLE_OLLAMA=true           # Enable Ollama consultant
-OLLAMA_MODEL=qwen2.5-coder:32b  # Model to use (premium default)
-OLLAMA_HOST=http://localhost:11434
+```bash
+ai-consultants init           # creates ~/.config/ai-consultants/{config.sh,.env}
+$EDITOR ~/.config/ai-consultants/.env
+```
 
-# Cost management
-MAX_SESSION_COST=1.00        # Budget limit in USD
-WARN_AT_COST=0.50            # Warning threshold
+For ad-hoc overrides without persisting, the most common knobs:
 
-# Panic mode
-PANIC_CONFIDENCE_THRESHOLD=5 # Trigger threshold
-PANIC_EXTRA_DEBATE_ROUNDS=1  # Additional rounds in panic mode
+```bash
+DEFAULT_PRESET=balanced      # minimal | balanced | thorough | high-stakes | fast | local | security
+DEFAULT_STRATEGY=majority    # majority | risk_averse | security_first | cost_capped | compare_only
+ENABLE_DEBATE=true           # Multi-agent debate (auto-skipped when consensus is high since v2.13)
+ENABLE_OLLAMA=true           # Enable local Ollama consultant
+MAX_SESSION_COST=1.00        # USD budget cap (paired with ENABLE_BUDGET_LIMIT=true to enforce)
 ```
 
+Full reference (~150 vars): [`references/configuration.md`](references/configuration.md). For category-aware preset suggestions: `ai-consultants doctor --suggest-preset --question "..."`.
+
 ### Doctor Command
 
-Diagnose and fix configuration issues:
+Diagnose, suggest, and fix:
 
 ```bash
-./scripts/doctor.sh              # Full diagnostic
-./scripts/doctor.sh --fix        # Auto-fix common issues
-./scripts/doctor.sh --json       # JSON output for automation
+ai-consultants doctor                                          # 22 health checks
+ai-consultants doctor --fix                                    # Auto-fix common issues
+ai-consultants doctor --json                                   # JSON for automation
+ai-consultants doctor --suggest-config                         # Print recommended ENABLE_* based on detected CLIs
+ai-consultants doctor --suggest-preset --question "..."        # Recommend preset + strategy for a question
 ```
 
 ---

package/SKILL.md

@@ -5,10 +5,10 @@ license: MIT
 compatibility: Requires bash, jq, and at least 2 AI CLI tools (gemini, codex, vibe, etc.). macOS and Linux.
 metadata:
   author: matteoscurati
-  version: 2.10.8
+  version: 2.14.1
 ---
 
-# AI Consultants v2.10.8 - AI Expert Panel
+# AI Consultants v2.14.1 - AI Expert Panel
 
 Simultaneously consult multiple AIs as "consultants" for coding questions. Each consultant has a **configurable persona** that influences their response style.
 

package/bin/ai-consultants

@@ -29,7 +29,16 @@ ensure_permissions() {
 ensure_permissions
 
 # --- Version ---
-VERSION="2.10.0"
+# Single source of truth: scripts/config.sh AI_CONSULTANTS_VERSION.
+# We grep instead of sourcing to avoid pulling in the full config (cost).
+# The sed pipeline succeeds even when its regex doesn't match (it returns
+# the input verbatim), so we explicitly validate the result is semver — else
+# the help banner would print garbage like "vAI_CONSULTANTS_VERSION=2.12.0".
+VERSION=$(grep -E '^AI_CONSULTANTS_VERSION=' "$SCRIPTS_DIR/config.sh" 2>/dev/null \
+    | head -1 | sed -E 's/.*"([^"]+)".*/\1/' || true)
+if ! [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+ ]]; then
+    VERSION="unknown"
+fi
 
 # --- Subcommand routing ---
 case "${1:-}" in
@@ -46,6 +55,7 @@ Usage:
   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
+  ai-consultants init [--force]               Scaffold ~/.config/ai-consultants/{config.sh,.env}
   ai-consultants install                      Install slash commands to ~/.claude/commands/
   ai-consultants version                      Show version
   ai-consultants help                         Show this help
@@ -68,6 +78,94 @@ EOF
     shift
     exec "$SCRIPTS_DIR/doctor.sh" "$@"
     ;;
+  init)
+    shift
+    FORCE=false
+    for arg in "$@"; do
+      [ "$arg" = "--force" ] && FORCE=true
+    done
+
+    # Reuse the canonical resolution from lib/user_config.sh.
+    # shellcheck source=../scripts/lib/user_config.sh
+    source "$SCRIPTS_DIR/lib/user_config.sh"
+    USER_DIR=$(get_user_config_dir)
+    if [ -z "$USER_DIR" ]; then
+      echo "Error: cannot resolve user config dir (HOME and XDG_CONFIG_HOME both unset)" >&2
+      echo "       export AI_CONSULTANTS_CONFIG_DIR=/path/to/your/config to override" >&2
+      exit 1
+    fi
+
+    # Refuse to write through a symlinked dir — protects against root running
+    # init when ~/.config/ai-consultants is a symlink to a sensitive path.
+    if [ -L "$USER_DIR" ]; then
+      echo "Error: $USER_DIR is a symlink. Refusing to scaffold into it." >&2
+      echo "       Remove the symlink, or point AI_CONSULTANTS_CONFIG_DIR elsewhere." >&2
+      exit 1
+    fi
+
+    # Pre-flight a write check so the user gets a friendly error instead of a
+    # mid-scaffold mkdir/cp failure.
+    parent="$(dirname "$USER_DIR")"
+    if [ ! -w "$parent" ] && [ ! -d "$USER_DIR" ]; then
+      echo "Error: cannot write to $parent" >&2
+      echo "       export AI_CONSULTANTS_CONFIG_DIR=/path/you/can/write to override" >&2
+      exit 1
+    fi
+
+    mkdir -p "$USER_DIR"
+    echo "User config dir: $USER_DIR"
+
+    # .env: copy from .env.example if present
+    DEST_ENV="$USER_DIR/.env"
+    SRC_ENV="$PROJECT_ROOT/.env.example"
+    if [ -f "$DEST_ENV" ] && [ "$FORCE" != true ]; then
+      echo "  ○ .env already exists (use --force to overwrite)"
+    elif [ -f "$SRC_ENV" ]; then
+      cp "$SRC_ENV" "$DEST_ENV"
+      chmod 600 "$DEST_ENV"
+      echo "  ✓ .env created from .env.example (chmod 600 — contains API keys)"
+    else
+      cat > "$DEST_ENV" <<'EOF'
+# AI Consultants user environment
+# KEY=value lines. Existing env vars take precedence.
+# Uncomment what you want to override.
+
+# ENABLE_DEBATE=true
+# DEFAULT_PRESET=balanced
+# DEFAULT_STRATEGY=majority
+# MAX_SESSION_COST=2.00
+# ENABLE_BUDGET_LIMIT=true
+EOF
+      chmod 600 "$DEST_ENV"
+      echo "  ✓ .env created (minimal template)"
+    fi
+
+    # config.sh: minimal sourceable bash starter
+    DEST_CFG="$USER_DIR/config.sh"
+    if [ -f "$DEST_CFG" ] && [ "$FORCE" != true ]; then
+      echo "  ○ config.sh already exists (use --force to overwrite)"
+    else
+      cat > "$DEST_CFG" <<'EOF'
+#!/bin/bash
+# ~/.config/ai-consultants/config.sh
+# Sourced after .env, before scripts/config.sh defaults are applied.
+# Use full bash logic. To defer to env vars, use ${VAR:-value}.
+#
+# Examples:
+# export DEFAULT_PRESET="${DEFAULT_PRESET:-balanced}"
+# export ENABLE_DEBATE="${ENABLE_DEBATE:-true}"
+# export AFFINITY_FILE="${AFFINITY_FILE:-$HOME/.config/ai-consultants/affinity.json}"
+EOF
+      echo "  ✓ config.sh created (minimal template)"
+    fi
+
+    echo ""
+    echo "Next steps:"
+    echo "  1. Edit $DEST_ENV to set API keys and overrides"
+    echo "  2. Run: ai-consultants doctor          # verify config is loaded"
+    echo "  3. Run: ai-consultants \"your question\"  # use the new defaults"
+    exit 0
+    ;;
   install)
     COMMANDS_SRC="$PROJECT_ROOT/.claude/commands"
     COMMANDS_DST="$HOME/.claude/commands"

package/docs/COST_RATES.md

@@ -1,4 +1,4 @@
-# Cost Rates - AI Consultants v2.10.8
+# Cost Rates - AI Consultants v2.14.1
 
 This page documents the per-token rates used by the cost tracking system.
 

package/docs/SMART_ROUTING.md

@@ -1,4 +1,4 @@
-# Smart Routing - AI Consultants v2.10
+# Smart Routing - AI Consultants v2.11
 
 The Smart Routing system automatically selects the most suitable consultants based on the question category.
 
@@ -17,20 +17,24 @@ MIN_AFFINITY=7
 
 ## Affinity Matrix
 
-Consultant-category affinity scores (scale 1-10):
-
-| Category | Gemini | Codex | Mistral | Kilo | Cursor | Aider | Amp | Kimi | Claude | Qwen3 | GLM | Grok | DeepSeek | MiniMax | Ollama |
-|----------|--------|-------|---------|------|--------|-------|-----|------|--------|-------|-----|------|----------|---------|--------|
-| **CODE_REVIEW** | 7 | **10** | 8 | 9 | 8 | 9 | 7 | 7 | 8 | 7 | 7 | 6 | 8 | 6 | 6 |
-| **BUG_DEBUG** | 7 | **10** | 9 | 8 | 8 | 9 | 7 | 6 | 7 | 7 | 6 | 6 | 8 | 5 | 6 |
-| **ARCHITECTURE** | **10** | 6 | 8 | 9 | 7 | 6 | **10** | 8 | 9 | 7 | 7 | 7 | 6 | 6 | 5 |
-| **ALGORITHM** | 9 | 8 | 7 | 8 | 7 | 7 | 7 | 6 | 8 | 8 | 8 | 7 | **10** | 6 | 6 |
-| **SECURITY** | 9 | 9 | **10** | 8 | 8 | 7 | 8 | 5 | 9 | 7 | 7 | 8 | 7 | 5 | 5 |
-| **QUICK_SYNTAX** | **10** | 8 | 5 | 6 | 7 | 7 | 5 | 5 | 7 | 7 | 6 | 5 | 7 | 5 | 6 |
-| **DATABASE** | 8 | 9 | 7 | 7 | 7 | 7 | 7 | 6 | 7 | 8 | 7 | 6 | 8 | 5 | 5 |
-| **API_DESIGN** | **10** | 9 | 7 | 8 | 8 | 6 | 9 | 6 | 8 | 7 | 7 | 7 | 6 | 6 | 5 |
-| **TESTING** | 7 | **10** | 9 | 7 | 8 | 9 | 7 | 5 | 7 | 7 | 7 | 6 | 7 | 6 | 5 |
-| **GENERAL** | 8 | 8 | 8 | 8 | 8 | 8 | 8 | 7 | 9 | 8 | 7 | 8 | 8 | 6 | 7 |
+Consultant-category affinity scores (scale 1-10) live in
+[`references/affinity.json`](../references/affinity.json) — the single source
+of truth at runtime. Prior to v2.11.0 the matrix was hard-coded as nested
+case statements in `scripts/lib/routing.sh`; it was extracted to JSON to make
+customization possible without editing bash.
+
+**Highlights from the default matrix:**
+
+| Category | Best match | Why |
+|----------|-----------|-----|
+| CODE_REVIEW | Codex (10), DeepSeek (10) | Code-specialist personas |
+| BUG_DEBUG | Codex (10) | Pragmatic debugger |
+| ARCHITECTURE | Gemini (10), Amp (10) | Big-picture design |
+| ALGORITHM | DeepSeek (10) | Algorithm specialist |
+| SECURITY | Mistral (10) | Devil's Advocate persona |
+| QUICK_SYNTAX | Gemini (10) | Fast turnaround |
+| API_DESIGN | Gemini (10) | API/system design |
+| TESTING | Codex (10), GLM (10) | Test generation |
 
 **Legend:**
 - **10**: Perfect match
@@ -38,6 +42,49 @@ Consultant-category affinity scores (scale 1-10):
 - 5-6: Medium match
 - 1-4: Poor match
 
+### Schema
+
+```json
+{
+  "version": "1.0",
+  "default_score": 5,
+  "general_score": 8,
+  "known_consultants": ["Gemini", "Codex", "..."],
+  "categories": {
+    "CODE_REVIEW": { "Gemini": 7, "Codex": 10, "..." },
+    "BUG_DEBUG":   { "..." }
+  }
+}
+```
+
+Lookup logic in `get_affinity(category, consultant)`:
+
+1. If `consultant` is not in `known_consultants` → `default_score`
+2. Else if `category` is not in `categories` (e.g. `GENERAL` or unrecognized) → `general_score`
+3. Else → `categories[category][consultant]`, falling back to `default_score` if missing
+
+### Custom Matrix Override
+
+Override the matrix at runtime by pointing `AFFINITY_FILE` at a custom JSON
+file with the same schema:
+
+```bash
+AFFINITY_FILE=~/my-affinity.json ./scripts/consult_all.sh "your question"
+```
+
+This is useful for:
+- Tweaking scores for a specific project (e.g., favoring DeepSeek for
+  algorithm-heavy codebases)
+- Disabling consultants for a category by setting their score below
+  `MIN_AFFINITY`
+- Experimenting with new categories before upstreaming them
+
+`./scripts/doctor.sh` validates the JSON schema and reports coverage gaps
+(consultants missing from a category).
+
+The matrix is loaded once per shell and cached in memory — no jq overhead
+on subsequent calls.
+
 ## Routing Modes
 
 The system automatically determines how many consultants to involve:

package/docs/cost_rates.json

@@ -1,5 +1,5 @@
 {
-  "version": "2.10.8",
+  "version": "2.14.1",
   "updated": "2026-05-03",
   "models": {
     "_comment_premium": "Premium tier models - May 2026",