@event4u/agent-config 9.2.0 → 9.4.0

package/docs/setup/per-ide/antigravity.md

@@ -2,8 +2,9 @@
 
 Antigravity (Google's agentic IDE) reads the Anthropic-shaped
 markdown skill bundle from its user-scope anchor `~/.agents/`. The
-package deploys via the universal skill convention; project-scope
-bridge is not yet wired (Phase 2.4 anchor).
+package deploys the universal skill bundle at global scope, the same
+projection its other bundle hosts get (codex, continue, roocode and
+the rest) — global-only by design, not a pending gap.
 
 ## Prerequisites
 
@@ -25,7 +26,11 @@ Populates:
 - `~/.agents/personas/` — review-lens personas
 
 (Project-scope `--tools=antigravity` is rejected with exit code 1
-— Antigravity has no documented project-discovery convention yet.)
+— every bundle host is global-only; the package writes the shared
+bundle to a user-scope anchor, not into the project. Antigravity does
+have a native project `.agents/` convention (`skills/`, `agents.md`,
+`workflows/`), but a project-scope projection is not part of the
+shipped surface.)
 
 ## How to use
 

package/docs/us-vs-the-category.md

@@ -0,0 +1,38 @@
+# Us vs. the category — the honest version
+
+<!-- claim:positioning-honest-nulls -->**The only agent layer that publishes
+the runs where it changed nothing.**<!-- /claim --> That line is deliberately
+falsifiable: find a comparable agent layer publishing its own honest-null
+benchmark runs and it updates — that is the point. The category's growth
+playbook is headline numbers nobody can re-run; ours is a claims ledger CI
+refuses to let drift.
+
+This page is the adoption-context frame around the CI-locked comparison table.
+The table itself lives on the proof page — every "our evidence" pointer is
+resolved by `task check-comparison` on every build, the category column only
+ever describes what is publicly observable, and no competitor is named or
+counter-claimed:
+
+**→ [The comparison table, CI-checked on every build](proof.md#4-what-is-checkable--us-vs-the-category)**
+
+## What the rows mean for an adopter
+
+- **No runtime.** Nothing to keep alive, nothing that writes state behind
+  you — the whole layer compiles into your host agent's own config surface.
+- **Published nulls.** The benchmark page keeps the runs where the package
+  changed *nothing* — including the persona-theater question: swapping the
+  advisor identities was measured at ~zero effect while the provider choice
+  mattered ~15× more, so persona identity was published as a placebo
+  (<!-- claim:persona-identity-placebo-null -->the persona-identity A/B is a
+  backed honest null<!-- /claim -->) instead of shipped as a feature. A
+  council implementation with falsifiable verdicts — including about itself.
+- **A wedge, not a funnel trap.** The 30-second entry is one read-only
+  subagent with a scoped, published eval behind its promise
+  ([what it catches](wedge/production-validator/README.md)) — the platform is
+  the second date, not the first.
+
+## Verify it yourself
+
+Every command on the [proof page § Verify it yourself](proof.md#5-verify-it-yourself)
+runs on a fresh checkout. If a claim here does not resolve, CI is red before
+you ever read it.

package/docs/wedge/production-validator/README.md

@@ -7,6 +7,14 @@ system — not just green tests over hollow code.
 
 One file. No install of anything else. No runtime, no daemon, no account.
 
+<!-- claim:wedge-hollow-detection -->On its published eval it returned the
+correct verdict on both fixtures — `NOT READY` with the exact `file:line` on a
+planted hollow implementation, `READY` with zero spurious findings on the clean
+control — at ~45k fewer tokens per task than the same check run inline
+([evidence](../../../internal/bench/orchestration/pv-a3-results.md)). Two
+planted fixtures on a Claude Code host — a scoped, reproducible promise, not a
+hit-rate.<!-- /claim -->
+
 ## What it does
 
 Before you call a feature done, `@production-validator` greps the shipped path
@@ -46,6 +54,22 @@ production-validator
   Final gate: NOT READY — refund() is a stub; validate against the real provider.
 ```
 
+## Optional: record your first run (local-only, opt-in)
+
+Nothing is measured unless you run it. After your first verdict, you can keep a
+private local record — one aggregate line, written into YOUR repo, no network:
+
+```bash
+bash <(curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/first-run-check.sh) ready
+```
+
+Outcomes: `ready` · `not-ready` · `abandoned`. The log
+(`.claude/wedge-first-run.local.log`) never leaves your machine — the package
+runs zero telemetry by default
+([contract](../../contracts/adoption-signal-floor.md)). The same outcome
+vocabulary feeds the proctored install-friction study
+(`agents/recruit-sessions/_install-friction-runbook.md`).
+
 ## Why this one
 
 It carries an anti-hallucination discipline (Evidence-First): "done" is a claim

package/docs/wedge/production-validator/first-run-check.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Opt-in, local-only first-run check for the production-validator wedge.
+#
+# Default-off by construction: nothing runs unless YOU invoke this script.
+# It writes ONE aggregate line to a local log in your repo and never opens a
+# network connection — consistent with the package's no-telemetry posture
+# (docs/contracts/adoption-signal-floor.md). Delete the log any time.
+#
+# Usage (after your first @production-validator verdict):
+#   bash first-run-check.sh ready       # first verdict was READY
+#   bash first-run-check.sh not-ready   # first verdict was NOT READY
+#   bash first-run-check.sh abandoned   # you gave up before a verdict
+#
+# The same outcome vocabulary feeds the B9 install-friction study
+# (agents/recruit-sessions/_install-friction-runbook.md) when a session is
+# proctored; unproctored users simply keep a private local record.
+set -euo pipefail
+
+OUTCOME="${1:-}"
+case "$OUTCOME" in
+  ready|not-ready|abandoned) ;;
+  *)
+    echo "usage: bash first-run-check.sh <ready|not-ready|abandoned>" >&2
+    exit 2
+    ;;
+esac
+
+AGENT_FILE=".claude/agents/production-validator.md"
+LOG_FILE=".claude/wedge-first-run.local.log"
+
+if [ ! -f "$AGENT_FILE" ]; then
+  echo "NOT INSTALLED — $AGENT_FILE missing. Install first:" >&2
+  echo "  mkdir -p .claude/agents && curl -fsSL https://raw.githubusercontent.com/event4u-app/agent-config/main/docs/wedge/production-validator/production-validator.md -o $AGENT_FILE" >&2
+  exit 1
+fi
+
+# One aggregate line: date + outcome. No user, host, repo, or content data.
+printf '%s wedge=production-validator first_run=%s\n' \
+  "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$OUTCOME" >> "$LOG_FILE"
+
+echo "Recorded locally in $LOG_FILE (never leaves this machine)."
+echo "Add it to .gitignore if you don't want it committed."

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "9.2.0",
+    "version": "9.4.0",
     "description": "Universal AI Agent OS — audited skills, governance rules, commands, and templates for AI coding tools (Claude Code, Cursor, Windsurf, Copilot).",
     "license": "MIT",
     "private": false,
@@ -70,7 +70,8 @@
         "lint:ts": "eslint 'src/**/*.ts'",
         "test:ts": "vitest run",
         "prepack": "npm run build && npm run build:discovery && npm run build:mcp-manifest && node src/scripts/prepack-check.mjs",
-        "prepublishOnly": "./scripts-run src/scripts/check_release_includes_discovery"
+        "prepublishOnly": "./scripts-run src/scripts/check_release_includes_discovery",
+        "prepare": "[ -d .git ] && bash src/scripts/install-hooks.sh || true"
     },
     "publishConfig": {
         "access": "public",

package/src/scripts/_lib/catalog_score.ts

@@ -0,0 +1,64 @@
+/**
+ * Catalog search scoring — a thin field-boosted wrapper over the shared
+ * `LexicalIndex` (BM25 + trigram prefilter).
+ *
+ * DECISION (road-to-persona-library-harvest.md Phase 2.3): the roadmap sketched
+ * porting the upstream Hermes `_score` (token overlap + name/description
+ * boosts). We do NOT — `_lib/lexical_index.ts` already ships a calibrated BM25
+ * core (ADR-061-sanctioned, dependency-free) with a coverage² multi-term
+ * weighting and a trigram candidate prefilter. Maintaining a second lexical
+ * scorer would be duplication. Instead we reuse `LexicalIndex` and get the
+ * field boost by REPEATING the name (×3) and description (×2) terms in each
+ * doc's indexed text, so a query term hitting the name outranks the same term
+ * buried in a tag. No new scorer.
+ */
+import type { CatalogIndexEntry } from '../build_catalog_index.js';
+import { LexicalIndex } from './lexical_index.js';
+
+export interface CatalogFilter {
+    cls?: CatalogIndexEntry['cls'];
+    /** Match against the entry's tags (packs/domain/tier). */
+    pack?: string;
+    limit?: number;
+}
+
+export interface CatalogHit {
+    entry: CatalogIndexEntry;
+    score: number;
+}
+
+/** Field-boosted searchable text: name ×3, description ×2, tags ×1. */
+function _docText(e: CatalogIndexEntry): string {
+    return [e.name, e.name, e.name, e.description, e.description, ...e.tags].join(' ');
+}
+
+function _filter(entries: readonly CatalogIndexEntry[], f: CatalogFilter): CatalogIndexEntry[] {
+    return entries.filter((e) => {
+        if (f.cls && e.cls !== f.cls) return false;
+        if (f.pack && !e.tags.includes(f.pack)) return false;
+        return true;
+    });
+}
+
+/**
+ * Rank catalog entries against a free-text query. The index is built over the
+ * (filtered) candidate set so IDF reflects the searched scope. Empty or
+ * whitespace query → no hits (a search tool must not dump the catalog).
+ */
+export function searchCatalog(
+    entries: readonly CatalogIndexEntry[],
+    query: string,
+    filter: CatalogFilter = {},
+): CatalogHit[] {
+    const q = query.trim();
+    if (q.length === 0) return [];
+    const candidates = _filter(entries, filter);
+    if (candidates.length === 0) return [];
+
+    const index = new LexicalIndex(candidates.map((e) => ({ id: e.id, text: _docText(e) })));
+    const byId = new Map(candidates.map((e) => [e.id, e]));
+    const limit = filter.limit && filter.limit > 0 ? filter.limit : 8;
+
+    const ranked = index.rank([q]).filter((r) => r.score > 0);
+    return ranked.slice(0, limit).map((r) => ({ entry: byId.get(r.id) as CatalogIndexEntry, score: r.score }));
+}

package/src/scripts/_lib/shingle_similarity.ts

@@ -0,0 +1,146 @@
+/**
+ * Entity-neutralized shingle-overlap primitive — the anti-reskin engine behind
+ * `lint_originality.ts`.
+ *
+ * Deterministic, no embeddings, no network. This is a DIFFERENT primitive from
+ * `text_similarity.ts` (token-set Jaccard, dedup) and `audit_skill_overlap.ts`
+ * (keyword-cosine, advisory) — both of which a find-replace re-skin
+ * ("Laravel" → "Symfony", "Vietnam" → "Korea") can defeat, because the swapped
+ * proper nouns shift the token/keyword vectors enough to drop the score.
+ *
+ * The defence is two-fold:
+ *   1. NEUTRALIZE entities — replace framework / vendor / language / region /
+ *      currency proper nouns with a single placeholder BEFORE comparison, so a
+ *      find-replace re-skin collapses to the original text.
+ *   2. SHINGLE — compare k-word shingles (default k = 8), not a bag of tokens,
+ *      so re-skins that only swap scattered nouns still share long verbatim
+ *      runs, and unrelated files that happen to share vocabulary do not.
+ *
+ * Overlap is CONTAINMENT (`|a∩b| / min(|a|,|b|)`), not Jaccard: a small file
+ * copied verbatim into a large padded one must still score high — the exact
+ * shape of an embedded re-skin.
+ *
+ * Deliberately does NOT touch `text_similarity.ts` or `memory_signal.ts`
+ * (byte-faithful parity contracts). This module is a new, additional layer.
+ */
+
+/**
+ * Proper-noun families that a find-replace re-skin swaps. Neutralized to a
+ * single placeholder so the swap does not move the score. Word-boundary
+ * matched, case-insensitive. **Extend via PR, never inline at a call site** —
+ * the list is the calibration surface, and a scattered entity list drifts.
+ *
+ * Seed the list from OUR corpus (the frameworks / vendors / regions the suite
+ * actually names), not from any external source.
+ */
+export const ENTITY_TERMS: readonly string[] = [
+    // Frameworks / libraries
+    'laravel', 'symfony', 'react', 'vue', 'preact', 'angular', 'svelte', 'nextjs',
+    'next', 'nuxt', 'livewire', 'flux', 'inertia', 'blade', 'tailwind', 'eloquent',
+    'doctrine', 'pest', 'phpunit', 'vitest', 'jest', 'playwright', 'express',
+    'fastify', 'django', 'flask', 'rails', 'spring',
+    // Languages
+    'php', 'typescript', 'javascript', 'python', 'ruby', 'golang', 'rust', 'java',
+    'kotlin', 'swift', 'csharp', 'elixir',
+    // Vendors / platforms / services
+    'aws', 'gcp', 'azure', 'hetzner', 'cloudflare', 'vercel', 'netlify', 'stripe',
+    'paddle', 'paypal', 'github', 'gitlab', 'bitbucket', 'linear', 'jira',
+    'confluence', 'slack', 'sentry', 'datadog', 'grafana', 'prometheus', 'redis',
+    'postgres', 'postgresql', 'mysql', 'mariadb', 'sqlite', 'mongodb', 'kafka',
+    'rabbitmq', 'terraform', 'terragrunt', 'kubernetes', 'docker', 'ansible',
+    'openai', 'anthropic', 'gemini', 'claude',
+    // Cloud regions / locales that re-skins swap
+    'us-east-1', 'us-west-2', 'eu-west-1', 'eu-central-1', 'ap-southeast-1',
+    // Currency codes / symbols
+    'usd', 'eur', 'gbp', 'chf', 'jpy',
+];
+
+const _ENTITY_RE = new RegExp(
+    `\\b(?:${ENTITY_TERMS.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|')})\\b`,
+    'gi',
+);
+
+/** Placeholder every entity family collapses to. Distinct token so it shingles. */
+export const ENTITY_PLACEHOLDER = 'entterm';
+
+/** Word token — mirrors the upstream re-skin gate's word regex so a calibrated
+ * threshold ports across corpora. Digits, `+ . # _ -` kept (e.g. `c#`, `9.3.0`). */
+const _WORD_RE = /[a-z0-9][a-z0-9+.#_-]*/g;
+
+/**
+ * Lowercase, strip frontmatter + markdown syntax, then replace entity proper
+ * nouns with `ENTITY_PLACEHOLDER`. `extra` is an optional caller-supplied regex
+ * (global) of additional terms to neutralize for one call (e.g. a corpus-
+ * specific product name); it never mutates the shared list.
+ */
+export function neutralizeEntities(text: string, extra?: RegExp): string {
+    let t = text;
+    // Leading YAML frontmatter.
+    t = t.replace(/^---\n[\s\S]*?\n---\n?/, '');
+    // Fenced code blocks (``` or ~~~).
+    t = t.replace(/^([`~]{3,}).*$[\s\S]*?^\1[ \t]*$/gm, ' ');
+    // HTML comments.
+    t = t.replace(/<!--[\s\S]*?-->/g, ' ');
+    // Inline code spans.
+    t = t.replace(/`[^`]*`/g, ' ');
+    // Links / images: keep the visible label, drop the target.
+    t = t.replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1');
+    t = t.toLowerCase();
+    // Heading / emphasis / list / blockquote / table punctuation → spaces, so
+    // the same prose scores identically regardless of markdown decoration.
+    t = t.replace(/[#*_>|~]+/g, ' ');
+    if (extra) {
+        t = t.replace(extra, ENTITY_PLACEHOLDER);
+    }
+    t = t.replace(_ENTITY_RE, ENTITY_PLACEHOLDER);
+    return t;
+}
+
+/** Ordered word tokens of the neutralized text (no set — shingles need order). */
+export function words(text: string): string[] {
+    return text.match(_WORD_RE) ?? [];
+}
+
+/**
+ * Word-level k-shingles over the neutralized token stream. A file with fewer
+ * than `k` tokens yields the empty set (guarded downstream → score 0, never
+ * NaN). Shingles join on a single space so they are comparable across files.
+ */
+export function shingles(text: string, k = 8): Set<string> {
+    const toks = words(neutralizeEntities(text));
+    const out = new Set<string>();
+    if (toks.length < k) {
+        return out;
+    }
+    for (let i = 0; i + k <= toks.length; i++) {
+        out.add(toks.slice(i, i + k).join(' '));
+    }
+    return out;
+}
+
+/**
+ * Containment overlap in percent: `100 * |a∩b| / min(|a|,|b|)`.
+ *
+ * Containment (not Jaccard) so a small file copied verbatim into a large padded
+ * one still scores high. Two empty shingle sets → 0 (a file too short to
+ * shingle carries no originality signal — never flag it). One empty → 0.
+ */
+export function overlapPercent(a: Set<string>, b: Set<string>): number {
+    const min = Math.min(a.size, b.size);
+    if (min === 0) {
+        return 0;
+    }
+    const [small, large] = a.size <= b.size ? [a, b] : [b, a];
+    let shared = 0;
+    for (const s of small) {
+        if (large.has(s)) {
+            shared++;
+        }
+    }
+    return (100 * shared) / min;
+}
+
+/** Convenience: shingle both texts and score. */
+export function shingleOverlap(a: string, b: string, k = 8): number {
+    return overlapPercent(shingles(a, k), shingles(b, k));
+}

package/src/scripts/ai_council/clients.ts

@@ -281,6 +281,27 @@ export abstract class ExternalAIClient {
         user_prompt: string,
         max_tokens?: number,
     ): CouncilResponse;
+
+    /**
+     * Cache-aware variant (A3 cross-round read unlock): the caller splits the
+     * user prompt into a byte-stable prefix (system + artefact — identical
+     * across rounds) and a volatile suffix (per-round critiques, stance
+     * contract). Clients with native prompt-cache support override this and
+     * place the cache breakpoint on the stable block only, so round N+1 READS
+     * the prefix instead of re-writing it. Default: plain concatenation —
+     * byte-identical to `ask()` for every transport without cache support.
+     */
+    ask_split(
+        system_prompt: string,
+        stable_prompt: string,
+        volatile_suffix: string,
+        max_tokens?: number,
+    ): CouncilResponse {
+        const user_prompt = volatile_suffix
+            ? `${stable_prompt}${volatile_suffix}`
+            : stable_prompt;
+        return this.ask(system_prompt, user_prompt, max_tokens);
+    }
 }
 
 /** Shared ctor-options shape for the API clients. */
@@ -395,6 +416,27 @@ export class AnthropicClient extends ExternalAIClient {
         user_prompt: string,
         max_tokens: number = DEFAULT_MAX_TOKENS,
     ): CouncilResponse {
+        return this._ask_impl(system_prompt, user_prompt, '', max_tokens);
+    }
+
+    override ask_split(
+        system_prompt: string,
+        stable_prompt: string,
+        volatile_suffix: string,
+        max_tokens: number = DEFAULT_MAX_TOKENS,
+    ): CouncilResponse {
+        return this._ask_impl(system_prompt, stable_prompt, volatile_suffix, max_tokens);
+    }
+
+    private _ask_impl(
+        system_prompt: string,
+        stable_prompt: string,
+        volatile_suffix: string,
+        max_tokens: number,
+    ): CouncilResponse {
+        const user_prompt = volatile_suffix
+            ? `${stable_prompt}${volatile_suffix}`
+            : stable_prompt;
         const t0 = _nowMs();
         let response: unknown;
         try {
@@ -426,12 +468,19 @@ export class AnthropicClient extends ExternalAIClient {
                       messages: [
                           {
                               role: 'user',
+                              // Breakpoint on the STABLE block only — the
+                              // volatile suffix (round critiques) rides after
+                              // it, so round N+1 reads the cached prefix
+                              // instead of re-writing it (A3 read unlock).
                               content: [
                                   {
                                       type: 'text',
-                                      text: user_prompt,
+                                      text: stable_prompt,
                                       cache_control: { type: 'ephemeral' },
                                   },
+                                  ...(volatile_suffix
+                                      ? [{ type: 'text', text: volatile_suffix }]
+                                      : []),
                               ],
                           },
                       ],

package/src/scripts/ai_council/config.ts

@@ -437,6 +437,13 @@ export interface NecessityClassifierConfig {
 export interface ModelDowngradeConfig {
     readonly enabled: boolean;
     readonly auto_apply: boolean;
+    /**
+     * Per-run escape hatch (roadmap A3): member name → model id. A member
+     * listed here is pinned to that model for the run — the size classifier
+     * and the cache-coupling gate are both skipped for it. Set it in
+     * `.ai-council.yml` when a specific artefact needs a specific tier.
+     */
+    readonly model_tier_override: Readonly<Record<string, string>>;
 }
 
 /** Pre-flight cost-disclosure toggle (Phase 8). */
@@ -908,11 +915,27 @@ function _build_model_downgrade(d: Dict): ModelDowngradeConfig {
     if (!_isBool(enabled)) {
         throw new CouncilConfigError('`model_downgrade.enabled` must be a bool.');
     }
-    const auto_apply = _get(d, 'auto_apply', false);
+    // A3 (2026-07-20): auto_apply default flipped to TRUE — auto-downgrade is
+    // the default and `auto_apply: false` (or `enabled: false`) is the opt-out.
+    // The cache-coupling gate in council_cli._size_fit_gate keeps it honest.
+    const auto_apply = _get(d, 'auto_apply', true);
     if (!_isBool(auto_apply)) {
         throw new CouncilConfigError('`model_downgrade.auto_apply` must be a bool.');
     }
-    return { enabled: Boolean(enabled), auto_apply: Boolean(auto_apply) };
+    const override_raw = _get(d, 'model_tier_override', {});
+    if (!_isDict(override_raw)) {
+        throw new CouncilConfigError('`model_downgrade.model_tier_override` must be a mapping.');
+    }
+    const model_tier_override: Record<string, string> = {};
+    for (const [k, v] of Object.entries(override_raw as Dict)) {
+        if (!_isStr(v) || (v as string).length === 0) {
+            throw new CouncilConfigError(
+                `\`model_downgrade.model_tier_override.${k}\` must be a non-empty string model id.`,
+            );
+        }
+        model_tier_override[k] = v as string;
+    }
+    return { enabled: Boolean(enabled), auto_apply: Boolean(auto_apply), model_tier_override };
 }
 
 function _build_cost_disclosure(d: Dict, scope: string): CostDisclosureConfig {
@@ -1308,7 +1331,8 @@ function _build_lens_overrides(d: Dict): LensOverridesConfig {
                     `\`lenses.${lens_name}.model_downgrade.enabled\` must be a bool.`,
                 );
             }
-            const md_auto = _get(md_block, 'auto_apply', false);
+            // Lens overrides inherit the A3 auto-by-default posture.
+            const md_auto = _get(md_block, 'auto_apply', true);
             if (!_isBool(md_auto)) {
                 throw new CouncilConfigError(
                     `\`lenses.${lens_name}.model_downgrade.auto_apply\` must be a bool.`,
@@ -1317,6 +1341,7 @@ function _build_lens_overrides(d: Dict): LensOverridesConfig {
             md_overrides.set(lens_name, {
                 enabled: Boolean(md_enabled),
                 auto_apply: Boolean(md_auto),
+                model_tier_override: {},
             });
         }
         const cd_block = lens_cfg.cost_disclosure;

package/src/scripts/ai_council/low_impact.ts

@@ -598,6 +598,10 @@ export function resolve_low_impact(
     clients: ReadonlyMap<string, ExternalAIClient> | Record<string, ExternalAIClient>,
     price_table: unknown = null,
     now: (() => Date) | null = null,
+    model_downgrade: {
+        enabled: boolean;
+        model_tier_override?: Readonly<Record<string, string>>;
+    } | null = null,
 ): FastPathResolution {
     if (!plan.is_resolvable) {
         return new FastPathResolution({
@@ -618,6 +622,18 @@ export function resolve_low_impact(
 
     for (const member of plan.members) {
         const client = getClient(member.name);
+        // A3: the fast-path is one-shot (no same-model cache reads to lose),
+        // so a configured ladder downgrades to its CHEAPEST rung outright —
+        // low-impact questions are the definition of small/low-stakes. The
+        // per-run model_tier_override pin wins; enabled: false opts out.
+        if (client && model_downgrade?.enabled) {
+            const pinned = model_downgrade.model_tier_override?.[member.name];
+            const cheapest = member.model_ladder.length > 0 ? member.model_ladder[0] : null;
+            const target = pinned && pinned.length > 0 ? pinned : cheapest;
+            if (target && target !== client.model) {
+                client.model = target;
+            }
+        }
         if (client === undefined || client === null) {
             answers.push(
                 new MemberAnswer({

package/src/scripts/ai_council/necessity.ts

@@ -402,6 +402,17 @@ function _length_tier(text: string): LengthTier {
  * @param lens active lens; `debate` lens disables downgrade suggestions to
  *   keep dissent quality high.
  * @returns A {@link SizeFitVerdict}.
+ *
+ * SIZE DEFINITION (A3 precondition, verified 2026-07-20): "small" is measured
+ * in Unicode code points (`_pyLen`, Python-`len()` parity) against the
+ * character thresholds `_SHORT_PROMPT_MAX`/`_MEDIUM_PROMPT_MAX` (200/800) plus
+ * a complexity-trigger heuristic — NOT bytes and NOT tokens. A token-based
+ * classifier was considered and rejected: it would add a tokenizer dependency
+ * (or a paid pre-flight count_tokens call) on the sequential-dispatch path
+ * (orchestrator.ts § "Members are called sequentially"), where every
+ * per-member pre-flight adds wall-clock latency before the first real call.
+ * The chars/4 heuristic in `pricing.estimate_input_tokens` remains the shared
+ * token approximation where cost math needs one.
  */
 export function classify_size_fit(
     prompt: string,