@event4u/agent-config 9.3.0 → 9.4.0

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,

package/src/scripts/ai_council/orchestrator.ts

@@ -484,7 +484,10 @@ export function consult(
 
     const spent: Spent = { input: 0, output: 0, usd: 0.0 };
     let last_results: CouncilResponse[] = [];
-    let current_user_prompt = question.user_prompt;
+    // A3 read unlock: the stable prefix is ALWAYS the original user prompt;
+    // per-round critiques + the STANCE contract ride in a volatile suffix so
+    // cache-capable clients read the [system + artefact] prefix on round N+1.
+    let current_suffix = '';
 
     const stance_tally = opts.stance_tally ?? false;
     for (let round_idx = 0; round_idx < rounds; round_idx++) {
@@ -492,11 +495,11 @@ export function consult(
         // contract when the tally is enabled. Off (default) → the original
         // question object flows through untouched, byte-identical to today.
         const is_final = round_idx === rounds - 1;
-        const base_prompt = round_idx === 0 ? question.user_prompt : current_user_prompt;
-        const prompt_for_round =
+        const suffix_for_round =
             is_final && stance_tally
-                ? `${base_prompt}\n\n---\n\n${STANCE_LINE_CONTRACT}`
-                : base_prompt;
+                ? `${current_suffix}\n\n---\n\n${STANCE_LINE_CONTRACT}`
+                : current_suffix;
+        const prompt_for_round = `${question.user_prompt}${suffix_for_round}`;
         const round_question =
             round_idx === 0 && prompt_for_round === question.user_prompt
                 ? question
@@ -511,16 +514,15 @@ export function consult(
             project,
             original_ask,
             advisor_plans,
+            split: suffix_for_round
+                ? { stable: question.user_prompt, suffix: suffix_for_round }
+                : null,
         });
         if (on_round_complete !== null) {
             on_round_complete(round_idx, last_results);
         }
         if (round_idx + 1 < rounds) {
-            current_user_prompt = _augment_for_next_round(
-                question.user_prompt,
-                last_results,
-                round_idx + 2,
-            );
+            current_suffix = _critique_suffix(last_results, round_idx + 2);
         }
     }
 
@@ -579,6 +581,14 @@ interface RunRoundOptions {
     project: ProjectContext | null;
     original_ask: string;
     advisor_plans?: Map<string, AdvisorPlan> | null;
+    /**
+     * A3 cross-round read unlock: when set, members are called via
+     * `ask_split(system, stable, suffix)` so cache-capable clients keep the
+     * breakpoint on the byte-stable [system + artefact] prefix and the
+     * per-round critiques ride behind it. `question.user_prompt` stays the
+     * full concatenation (estimates + persistence unchanged).
+     */
+    split?: { stable: string; suffix: string } | null;
 }
 
 /** Run a single round; mutate `spent` with cumulative totals. */
@@ -626,11 +636,18 @@ function _run_round(
         if (!(_getattr(member, 'billable', true) as boolean)) {
             let response: CouncilResponse;
             try {
-                response = member.ask(
-                    _system_prompt_for_member(member),
-                    question.user_prompt,
-                    question.max_tokens,
-                );
+                response = opts.split
+                    ? member.ask_split(
+                          _system_prompt_for_member(member),
+                          opts.split.stable,
+                          opts.split.suffix,
+                          question.max_tokens,
+                      )
+                    : member.ask(
+                          _system_prompt_for_member(member),
+                          question.user_prompt,
+                          question.max_tokens,
+                      );
             } catch (exc) {
                 response = new CouncilResponse({
                     provider: member.name,
@@ -702,11 +719,18 @@ function _run_round(
         // ── actual call ──────────────────────────────────────────────
         let response: CouncilResponse;
         try {
-            response = member.ask(
-                _system_prompt_for_member(member),
-                question.user_prompt,
-                question.max_tokens,
-            );
+            response = opts.split
+                ? member.ask_split(
+                      _system_prompt_for_member(member),
+                      opts.split.stable,
+                      opts.split.suffix,
+                      question.max_tokens,
+                  )
+                : member.ask(
+                      _system_prompt_for_member(member),
+                      question.user_prompt,
+                      question.max_tokens,
+                  );
         } catch (exc) {
             response = new CouncilResponse({
                 provider: member.name,
@@ -796,6 +820,19 @@ function _augment_for_next_round(
     original_prompt: string,
     prior_responses: CouncilResponse[],
     next_round_number: number,
+): string {
+    return `${original_prompt}${_critique_suffix(prior_responses, next_round_number)}`;
+}
+
+/**
+ * The volatile per-round block ONLY (A3 read unlock) — everything after the
+ * byte-stable original prompt. Empty string when no prior response survives.
+ * `_augment_for_next_round` = original + this; the rounds loop feeds this to
+ * `ask_split` so the cached [system + artefact] prefix stays byte-identical.
+ */
+function _critique_suffix(
+    prior_responses: CouncilResponse[],
+    next_round_number: number,
 ): string {
     const blocks: string[] = [];
     let label_idx = 0;
@@ -808,11 +845,11 @@ function _augment_for_next_round(
         blocks.push(`### Reviewer ${label}\n\n${_pyStrip(r.text)}`);
     }
     if (blocks.length === 0) {
-        return original_prompt;
+        return '';
     }
     const prior_block = blocks.join('\n\n');
     return (
-        `${original_prompt}\n\n` +
+        `\n\n` +
         `---\n\n` +
         `## Prior round critiques (round ${next_round_number - 1})\n\n` +
         `You are now in round ${next_round_number}. Below are anonymised\n` +
@@ -910,6 +947,15 @@ function _augment_for_debate_round(
     // Phase 3: when the debate gates are enabled, prepend the anti-conformity
     // directive. Default `false` keeps the prompt byte-identical to today.
     anti_conformity = false,
+): string {
+    return `${original_prompt}${_debate_suffix(prior_responses, next_round_number, anti_conformity)}`;
+}
+
+/** Debate twin of `_critique_suffix` — the volatile block only (A3). */
+function _debate_suffix(
+    prior_responses: CouncilResponse[],
+    next_round_number: number,
+    anti_conformity = false,
 ): string {
     const blocks: string[] = [];
     let label_idx = 0;
@@ -922,12 +968,12 @@ function _augment_for_debate_round(
         blocks.push(`### Reviewer ${label}\n\n${_pyStrip(r.text)}`);
     }
     if (blocks.length === 0) {
-        return original_prompt;
+        return '';
     }
     const prior_block = blocks.join('\n\n');
     const anti_conformity_block = anti_conformity ? `${ANTI_CONFORMITY_DIRECTIVE}\n\n` : '';
     return (
-        `${original_prompt}\n\n` +
+        `\n\n` +
         `---\n\n` +
         `## Prior round positions (round ${next_round_number - 1})\n\n` +
         `You are now in round ${next_round_number} of a structured\n` +
@@ -1122,6 +1168,9 @@ export function run_debate(
 
     const spent: Spent = { input: 0, output: 0, usd: 0.0 };
     const all_rounds: CouncilResponse[][] = [];
+    // A3 read unlock (debate twin): stable prefix = the original prompt; the
+    // per-round positions block rides in a volatile suffix (see consult loop).
+    let current_suffix = '';
     let current_user_prompt = question.user_prompt;
 
     // Phase 3 restate: one pre-round-1 call per member. Runs BEFORE any debate
@@ -1167,6 +1216,9 @@ export function run_debate(
                 project,
                 original_ask,
                 advisor_plans,
+                split: current_suffix
+                    ? { stable: question.user_prompt, suffix: current_suffix }
+                    : null,
             });
         }
 
@@ -1195,12 +1247,12 @@ export function run_debate(
         // Prep the user-prompt for the next round so the cost estimate
         // below covers the augmented bytes.
         if (round_idx + 1 < max_rounds) {
-            current_user_prompt = _augment_for_debate_round(
-                question.user_prompt,
+            current_suffix = _debate_suffix(
                 results,
                 round_number + 1,
                 opts.debate_gates ?? false,
             );
+            current_user_prompt = `${question.user_prompt}${current_suffix}`;
             // Hard-cap + continue-prompt gating before kicking off N+1.
             let next_round_usd: number;
             if (table !== null) {

package/src/scripts/ai_council/pricing.ts

@@ -119,6 +119,65 @@ export interface CacheTokenBreakdown {
     output_tokens: number;
 }
 
+/** A1↔A3 coupling verdict for a proposed model downgrade (Phase A3). */
+export interface DowngradeCoupling {
+    /** Full-rate cost delta per call: estimate(current) − estimate(suggested). */
+    downgrade_savings_usd: number;
+    /**
+     * Cache value forfeited by leaving the current model: the prompt cache is
+     * model-scoped, so a downgraded member re-pays the full input rate on the
+     * span that would have been read back at CACHE_READ_MULTIPLIER.
+     */
+    lost_cache_savings_usd: number;
+    /** True iff downgrade_savings_usd > lost_cache_savings_usd. */
+    net_positive: boolean;
+}
+
+/**
+ * Decide whether a suggested downgrade is net-positive AFTER accounting for
+ * the model-scoped prompt cache (roadmap A3 gate: downgrade only when
+ * `downgrade_savings > lost_cache_savings`).
+ *
+ * `cache.expected_reads` is the number of same-model cache reads the run
+ * would plausibly realize at the CURRENT model (rounds − 1 on multi-round
+ * runs, 0 on one-shot paths like the low-impact fast-path). With caching
+ * disabled the lost term is 0 and any cheaper model wins.
+ */
+export function downgrade_coupling(
+    provider: string,
+    current_model: string,
+    suggested_model: string,
+    input_tokens: number,
+    max_output_tokens: number,
+    cache: {
+        enabled: boolean;
+        cacheable_prefix_tokens: number;
+        expected_reads: number;
+    },
+    table: PriceTable,
+): DowngradeCoupling {
+    const cur = estimate_cost(provider, current_model, input_tokens, max_output_tokens, table);
+    const sug = estimate_cost(provider, suggested_model, input_tokens, max_output_tokens, table);
+    const downgrade_savings_usd =
+        cur.input_usd + cur.output_usd - (sug.input_usd + sug.output_usd);
+    let lost_cache_savings_usd = 0;
+    if (cache.enabled && cache.expected_reads > 0 && cache.cacheable_prefix_tokens > 0) {
+        const cur_rates = lookup(table, provider, current_model);
+        if (cur_rates !== null) {
+            lost_cache_savings_usd =
+                (cache.cacheable_prefix_tokens / 1_000_000) *
+                cur_rates.input_per_1m_usd *
+                (1 - CACHE_READ_MULTIPLIER) *
+                cache.expected_reads;
+        }
+    }
+    return {
+        downgrade_savings_usd,
+        lost_cache_savings_usd,
+        net_positive: downgrade_savings_usd > lost_cache_savings_usd,
+    };
+}
+
 /**
  * Realized cost of a call given OBSERVED cache-token counts (from
  * `CouncilResponse.usage`). Deliberately separate from `estimate_cost`, which

package/src/scripts/ai_council/stance_tally.ts

@@ -59,6 +59,37 @@ export interface StanceTallyResult {
 const _STANCE_RE =
     /STANCE:\s*(.+?)\s*\|\s*CONFIDENCE:\s*(high|med(?:ium)?|low)\s*\|\s*DEALBREAKER:\s*(yes|no)/gi;
 
+
+/** Run the strict stance grammar; return the LAST match or null. */
+function _last_stance_match(text: string): RegExpExecArray | null {
+    _STANCE_RE.lastIndex = 0;
+    let last: RegExpExecArray | null = null;
+    let m: RegExpExecArray | null;
+    while ((m = _STANCE_RE.exec(text)) !== null) {
+        last = m;
+    }
+    return last;
+}
+
+/**
+ * Normalize the two cosmetic defect classes the lenient pass forgives, on
+ * lines that mention STANCE only: markdown emphasis characters and comma /
+ * semicolon field separators. Everything else is left byte-identical.
+ */
+export function _normalize_stance_cosmetics(text: string): string {
+    return text
+        .split('\n')
+        .map((line) => {
+            if (!/stance/i.test(line)) {
+                return line;
+            }
+            let out = line.replace(/[*_`]/g, '');
+            out = out.replace(/\s*[;,]\s*(?=(?:CONFIDENCE|DEALBREAKER)\b)/gi, ' | ');
+            return out;
+        })
+        .join('\n');
+}
+
 /**
  * Parse the member's stance line from their reply text. Returns the LAST stance
  * line if several appear (the final, most-authoritative one), or `null` when no
@@ -66,11 +97,17 @@ const _STANCE_RE =
  * infers a stance from the surrounding prose.
  */
 export function parse_stance_line(text: string): Omit<StanceLine, 'member'> | null {
-    _STANCE_RE.lastIndex = 0;
-    let last: RegExpExecArray | null = null;
-    let m: RegExpExecArray | null;
-    while ((m = _STANCE_RE.exec(text)) !== null) {
-        last = m;
+    let last = _last_stance_match(text);
+    if (last === null) {
+        // Lenient fallback (A3 repair-tightening): a stance whose only defect
+        // is cosmetic — markdown emphasis around the field names (`**STANCE:**`),
+        // or `,`/`;` used where the contract says `|` — is NOT "genuinely
+        // unparseable" and must not burn a repair call. Normalize those two
+        // defect classes on stance-bearing lines only, then re-run the SAME
+        // strict grammar. Anything the strict grammar still rejects (missing
+        // fields, invalid enum values, no STANCE line at all) stays a repair
+        // marker — leniency never invents a stance from prose.
+        last = _last_stance_match(_normalize_stance_cosmetics(text));
     }
     if (last === null) {
         return null;