From 24b0f359606ae592c6f425df5ab77037cc582f73 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 16 Nov 2026 20:31:06 +0100 Subject: [PATCH 1/3] feat(model-router): Fable leaves auto-routing, Opus heads best and big Fable is the advisor now: the best and big tiers default to opus then sonnet, the row dialog drops it, and the ask-before-Fable dialog runs only when an override heads best with fable. Fable stays ranked and hand-pickable. --- lib/tests/effort-routing.test.sh | 13 +- mods/model-router/hooks/register.test.ts | 330 +++++++++++++++++------ mods/model-router/hooks/register.ts | 51 ++-- 3 files changed, 288 insertions(+), 106 deletions(-) diff --git a/lib/tests/effort-routing.test.sh b/lib/tests/effort-routing.test.sh index 34545d1..c398842 100755 --- a/lib/tests/effort-routing.test.sh +++ b/lib/tests/effort-routing.test.sh @@ -53,19 +53,13 @@ code_phase() { awk '/^ phases: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$REG" \ | sed -nE "s/^ *$1: \{ tier: '([a-z]+)', effort: '([a-z]+)' \},?$/\1 \2/p" } -# tier_floor -> the model: floor of a tier's agents -# a best-tier row floors on its 2nd alias: inTier keeps the frontmatter when the head is down (Fable credits, BLK-030); a fable floor would spawn the gates on a dead model -tier_floor() { - if [ "$2" != best ]; then tier_head "$1" "$2"; return; fi - awk '/^ tiers: \{/{f=1;next} f&&/^ \},?$/{f=0} f' "$1" \ - | sed -nE "s/^ *best: \['[a-z]+', '([a-z]+)'.*$/\1/p" -} # field_of -> that phase's frontmatter value +# best is headed by opus since 2026-11-16: the floor is the tier head field_of() { local pe tier pe="$(phase_effort "$1" "$2")" if [ "$3" = effort ]; then printf '%s\n' "${pe#* }"; return; fi - tier="${pe% *}"; tier_floor "$REG" "$tier" + tier="${pe% *}"; tier_head "$REG" "$tier" } # verdict : ok when the # frontmatter equals the row's phase; warn when the row was changed through @@ -119,8 +113,7 @@ FD="$(dump "$FIX/routing.json")" [ "$(phase_effort "$FD" judge)" = "big xhigh" ] && ok || ko "flip: phase" [ -z "$(phase_effort "$FD" nothere)" ] && ok || ko "flip: ghost phase" [ "$(tier_head "$FIX/reg.ts" big)" = "opus" ] && ok || ko "flip: tier head" -[ "$(tier_floor "$FIX/reg.ts" best)" = opus ] && ok || ko "flip: best floors on its 2nd alias" -[ "$(tier_floor "$FIX/reg.ts" big)" = opus ] && ok || ko "flip: big floors on its head" +[ "$(tier_head "$FIX/reg.ts" best)" = fable ] && ok || ko "flip: best head" [ "$(changed_of "$FD" skills feat)" = "reflect implement" ] && ok || ko "flip: changed entry" [ -z "$(changed_of "$FD" skills doc)" ] && ok || ko "flip: ghost changed entry" # the drift verdicts (high = reflect's effort, medium = implement's) diff --git a/mods/model-router/hooks/register.test.ts b/mods/model-router/hooks/register.test.ts index 2fd2174..1b2e66a 100644 --- a/mods/model-router/hooks/register.test.ts +++ b/mods/model-router/hooks/register.test.ts @@ -75,6 +75,7 @@ type Fixture = { answers?: string[] repo?: World['repo'] noHome?: boolean // HOME unset: env.get answers undefined + legacyTiers?: boolean // machine override puts fable back in best and big surfaces?: readonly string[] // default ['terminal'] clockFailsAfterAsk?: boolean // see World; the rig gets no MockClock sleepFails?: boolean // see World; the rig gets no MockClock @@ -118,6 +119,21 @@ const baseRouting = (): Rec => ({ askTier: false, }) +// The tiers shipped before 2026-11-16: fable heads best, opus heads big. +const LEGACY_TIERS = { + best: ['fable', 'opus', 'sonnet'], + big: ['opus', 'fable', 'sonnet'], +} + +/** The fixture's home file, with the legacy tiers merged under it. */ +function homeOf(fx: Fixture): Fixture['home'] { + if (!fx.legacyTiers) return fx.home + if (fx.noHome || fx.home === 'broken') { + throw new Error('legacyTiers needs a readable machine override') + } + return { tiers: LEGACY_TIERS, ...fx.home } +} + function newWorld(fx: Fixture = {}): World { const file = baseRouting() file.ask = fx.ask ?? false @@ -128,9 +144,9 @@ function newWorld(fx: Fixture = {}): World { else if (fx.routing !== 'absent') { files.set('routing', JSON.stringify(file, null, 2)) } - if (fx.home !== undefined) { - files.set(HOME_FILE, - fx.home === 'broken' ? '{nope' : JSON.stringify(fx.home)) + const home = homeOf(fx) + if (home !== undefined) { + files.set(HOME_FILE, home === 'broken' ? '{nope' : JSON.stringify(home)) } return { files, @@ -489,7 +505,7 @@ test('the main step carries the routed effort, model untouched', async ( await boot($, on) await $.tool.call({ tool: 'mcp__model-router__route', phase: 'plan' }) await runStep($, stepInput()) - expect(seen).toEqual([{ model: 'claude-fable-5-2', effort: 'xhigh' }]) + expect(seen).toEqual([{ model: 'claude-opus-5-5', effort: 'xhigh' }]) }) test('a tabled agent steps at its table effort', async ($, on) => { @@ -809,12 +825,12 @@ async function bootRigVar( return { rig: await bootRig($, on, model, null, world), usage } } -test('tier: a plan route upgrades a haiku session to fable xhigh', async ( +test('tier: a plan route upgrades a haiku session to opus xhigh', async ( $, on) => { const rig = await bootRig($, on, HAIKU) await planRoute($) expect(await stepOn($, rig, HAIKU)).toEqual({ - model: FABLE, + model: OPUS, effort: 'xhigh', }) }) @@ -823,7 +839,7 @@ test('tier: show prints the resolved id of each phase and a down line', async ( $, on) => { await bootRig($, on) const text = await route($, 'show') - expect(text).toContain('plan=best→claude-fable-5-2/xhigh') + expect(text).toContain('plan=best→claude-opus-5-5/xhigh') expect(text).toContain('judge=big→claude-opus-5-5/xhigh') expect(text).toContain('down: none') }) @@ -925,7 +941,7 @@ test('haiku 5: a plan keyword on a haiku session is xhigh', async ( test('fallback: a rate limit on fable moves plan to opus max', async ( $, on) => { - const rig = await bootRig($, on) + const rig = await bootRig($, on, FABLE, 1000, legacyWorld()) await planRoute($) expect((await stepOn($, rig, FABLE)).model).toBe(FABLE) await failWith($, 'rate_limit') @@ -955,7 +971,7 @@ test('breaker: an invalid_request or a turn error never marks down', async ( test('breaker: the hold lapses with the clock, a second one doubles', async ( $, on) => { - const rig = await bootRig($, on) + const rig = await bootRig($, on, FABLE, 1000, legacyWorld()) await planRoute($) await stepOn($, rig, FABLE) await failWith($, 'overloaded') @@ -970,7 +986,7 @@ test('breaker: the hold lapses with the clock, a second one doubles', async ( test('breaker: a /model command clears the mark of its target', async ( $, on) => { - const rig = await bootRig($, on) + const rig = await bootRig($, on, FABLE, 1000, legacyWorld()) await planRoute($) await stepOn($, rig, FABLE) await failWith($, 'rate_limit') @@ -1014,7 +1030,7 @@ test('unknown: the haiku alias id is in the table, a route moves it', async ( const logs = recordLogs(on) const rig = await bootRig($, on, HAIKU) await planRoute($) - expect((await stepOn($, rig, HAIKU)).model).toBe(FABLE) + expect((await stepOn($, rig, HAIKU)).model).toBe(OPUS) expect(logsWith(logs, 'unknown to the models table')).toBe(0) }) @@ -1090,7 +1106,7 @@ test('per axis: a model-less sticky never hides a turn route tier', async ( const rig = await bootRig($, on, HAIKU) await route($, 'effort=low') await planRoute($) - expect(await stepOn($, rig, HAIKU)).toEqual({ model: FABLE, effort: 'low' }) + expect(await stepOn($, rig, HAIKU)).toEqual({ model: OPUS, effort: 'low' }) }) // ---- texts follow the decision, from the turn's model ------------------ @@ -1117,12 +1133,12 @@ test('text: show names the session model after the turn ended', async ( $, on) => { const rig = await bootRig($, on, HAIKU) await planRoute($) - expect((await stepOn($, rig, HAIKU)).model).toBe(FABLE) + expect((await stepOn($, rig, HAIKU)).model).toBe(OPUS) await endTurn($) await route($, 'mechanical') const line = mainLine(await route($, 'show')) expect(line).toContain(`model ${HAIKU}`) - expect(line).not.toContain(FABLE) + expect(line).not.toContain(OPUS) }) test('text: show reflects a /model command to opus', async ($, on) => { @@ -1180,6 +1196,10 @@ async function bootRun( return bootRig($, on, model, tokens, world) } +/** A world on the pre-2026-11-16 tiers: fable heads best (LEGACY tests). */ +const legacyWorld = (fx: Fixture = {}): World => + newWorld({ legacyTiers: true, ...fx }) + const spawnOf = (agent: string, extra: object = {}) => ({ ...spawnInput(), subagentType: agent, ...extra }) @@ -1308,7 +1328,7 @@ test('run slot: a model-loaded helper skill moves effort only', async ( await loadSkill($, 'feat') await loadSkill($, 'using-git-worktrees') expect(mainLine(await route($, 'show'))).toContain('skill mechanical') - expect(await stepOn($, rig, FABLE)).toEqual({ model: FABLE, effort: 'low' }) + expect(await stepOn($, rig, FABLE)).toEqual({ model: OPUS, effort: 'low' }) await endTurn($) expect(mainLine(await route($, 'show'))).toContain('run reflect') }) @@ -1369,7 +1389,7 @@ test('route answer names the id even with a floor in force', async ( await ultrathink($) const out = await $.tool.call({ tool: ROUTE_TOOL, phase: 'plan' }) const text = JSON.stringify(out) - expect(text).toContain(`model ${FABLE}`) + expect(text).toContain(`model ${OPUS}`) expect(text).toContain('user floor max') }) @@ -1403,12 +1423,12 @@ test('agent skill: a rowed one writes the loop effort', async ($, on) => { expect(await effortAfterSkill($, on, 'status')).toBe('low') }) -test('agent row: judge moves up to fable when opus is down', async ( +test('agent row: judge keeps its frontmatter when opus is down', async ( $, on) => { const rig = await bootRun($, on) await switchTo($, OPUS, SONNET, 'auto') await $.agent.spawn(spawnOf('plan-challenger')) - expect(rig.specs).toEqual([FABLE]) + expect(rig.specs).toEqual([undefined]) }) test('agent row: opus and fable down, no write and one log line', async ( @@ -1426,14 +1446,15 @@ test('agent row: opus and fable down, no write and one log line', async ( ]) }) -const auditWorld = () => newWorld({ +const auditWorld = (fx: Fixture = {}) => newWorld({ + ...fx, edit: f => { (f.agents as Rec)['security-auditor'] = 'audit' }, }) test('audit row: fable down, no write, frontmatter runs', async ( $, on) => { const logs = recordLogs(on) - const rig = await bootRun($, on, FABLE, auditWorld()) + const rig = await bootRun($, on, FABLE, auditWorld({ legacyTiers: true })) await switchTo($, FABLE, SONNET, 'auto') await $.agent.spawn(spawnOf('security-auditor')) expect(rig.specs).toEqual([undefined]) @@ -1445,7 +1466,7 @@ test('audit row: fable down, no write, frontmatter runs', async ( test('audit row: first spawn dies on fable, the retry lands on the floor', async ($, on) => { - const rig = await bootRun($, on, FABLE, auditWorld()) + const rig = await bootRun($, on, FABLE, auditWorld({ legacyTiers: true })) await $.agent.spawn(spawnOf('security-auditor')) await failWith($, 'rate_limit', 'a1') await $.agent.spawn(spawnOf('security-auditor')) @@ -1738,7 +1759,7 @@ test('layers: an invalid routing.json phase falls back by name', async ( }) await bootRun($, on, FABLE, w) const text = await route($, 'show') - expect(text).toContain('reflect=best→claude-fable-5-2/high') + expect(text).toContain('reflect=best→claude-opus-5-5/high') expect(logs.join('\n')).toContain('config phases.reflect ignored') }) @@ -1757,7 +1778,7 @@ test('layers: a routing.json phase gone missing falls back, logged', async ( const logs = recordLogs(on) const w = newWorld({ edit: f => { delete (f.phases as Rec).reflect } }) await bootRun($, on, FABLE, w) - expect(await route($, 'show')).toContain('reflect=best→claude-fable-5-2/high') + expect(await route($, 'show')).toContain('reflect=best→claude-opus-5-5/high') expect(logs.filter(l => l.includes('lacks phases'))).toEqual([ 'model-router: routing.json lacks phases reflect; code defaults kept', ]) @@ -1852,7 +1873,7 @@ test('layers: routing.json unreadable at start means defaults, no rows', async ( const w = newWorld({ routing: 'broken', ask: true }) const rig = await bootRun($, on, FABLE, w) expect(await featerModel($, rig)).toBeUndefined() - expect(await route($, 'show')).toContain('plan=best→claude-fable-5-2/xhigh') + expect(await route($, 'show')).toContain('plan=best→claude-opus-5-5/xhigh') const said = logs.filter(l => l.includes('routing.json unreadable')) expect(said).toHaveLength(1) }) @@ -2026,7 +2047,7 @@ test('T1: a typed skill asks once, with the real id and effort', async ( expect(w.asked).toHaveLength(1) const first = w.asked[0] as Asked expect(first.text).toContain('/feat') - expect(first.text).toContain('claude-fable-5-2 at high') + expect(first.text).toContain('claude-opus-5-5 at high') expect(first.options).toEqual(['Later', 'Keep', 'Change']) expect(first.header).toBe('model-router') }) @@ -2036,7 +2057,7 @@ test('T1: the question follows the model main will really run on', async ( const w = asks(['Later']) await bootRun($, on, SONNET, w) await typeFeat($) - expect(w.asked[0]?.text).toContain('claude-fable-5-2 at high') + expect(w.asked[0]?.text).toContain('claude-opus-5-5 at high') }) test('T1: Keep writes the row and its phase, then the skill never asks', async ( @@ -2561,7 +2582,7 @@ test('T2: Keep writes the agent row and the spawn goes on', async ($, on) => { test('T2: a change routes this very spawn with the new row', async ( $, on) => { - const w = asks([...TO_JUDGE, 'Everywhere']) + const w = asks([...TO_JUDGE, 'Everywhere'], { legacyTiers: true }) const rig = await bootRun($, on, FABLE, w) await $.agent.spawn(spawnOf('feater')) expect(rig.specs).toEqual([OPUS]) @@ -2657,7 +2678,7 @@ test('T3: a phase declared through the route tool asks Keep or Later', async ( await $.tool.call({ tool: ROUTE_TOOL, phase: 'orchestrate' }) const q = w.asked[0] as Asked expect(q.text).toContain('First use of orchestrate on the main loop') - expect(q.text).toContain('claude-fable-5-2 at medium') + expect(q.text).toContain('claude-opus-5-5 at medium') expect(q.options).toEqual(['Later', 'Keep']) }) @@ -2811,7 +2832,7 @@ test('layers: enabled:false in the override survives /clear', async ( const skillPath = (name: string) => `${HOME}/.claude/skills/${name}/SKILL.md` const skillMd = (front: string, body = '# body') => `---\nname: feat\n${front}\nallowed-tools: Read\n---\n${body}\n` -const ROUTED = 'Routed to reflect: claude-fable-5-2 at high. OK?' +const ROUTED = 'Routed to reflect: claude-opus-5-5 at high. OK?' /** A typed /feat with `md` served as its SKILL.md; the world after. */ async function featWith( @@ -2947,7 +2968,7 @@ test('text: the phase about shows in the skill question', async ($, on) => { const w = await featWith($, on, undefined, { edit: setPhase('reflect', { about: 'deep thinking' }) }) expect(w.asked[0]?.text).toBe('First route for /feat. Routed to reflect ' + - '(deep thinking): claude-fable-5-2 at high. OK?') + '(deep thinking): claude-opus-5-5 at high. OK?') }) test('text: the about is cleaned before it enters a question', async ( @@ -3014,7 +3035,7 @@ test('text: a phase question names its about and its consumers', async ( await $.tool.call({ tool: ROUTE_TOOL, phase: 'orchestrate' }) expect(w.asked[0]?.text).toBe('First use of orchestrate on the main loop — ' + 'dispatch work; used by 0 rows, the derived route of dispatches: ' + - 'claude-fable-5-2 at medium. OK?') + 'claude-opus-5-5 at medium. OK?') }) test('text: a phase question counts rows and prompt rules', async ($, on) => { @@ -3022,7 +3043,7 @@ test('text: a phase question counts rows and prompt rules', async ($, on) => { await bootRun($, on, FABLE, w) await $.tool.call({ tool: ROUTE_TOOL, phase: 'reflect' }) expect(w.asked[0]?.text).toBe('First use of reflect on the main loop — ' + - 'used by 1 row, 1 prompt rule: claude-fable-5-2 at high. OK?') + 'used by 1 row, 1 prompt rule: claude-opus-5-5 at high. OK?') }) test('text: a phase question names its floor rule', async ($, on) => { @@ -3030,7 +3051,7 @@ test('text: a phase question names its floor rule', async ($, on) => { await bootRun($, on, FABLE, w) await $.tool.call({ tool: ROUTE_TOOL, phase: 'escalate' }) expect(w.asked[0]?.text).toBe('First use of escalate on the main loop — ' + - 'used by 0 rows, 1 floor rule: claude-fable-5-2 at max. OK?') + 'used by 0 rows, 1 floor rule: claude-opus-5-5 at max. OK?') }) test('T3: a Change answer changes nothing and is said', async ($, on) => { @@ -3043,19 +3064,19 @@ test('T3: a Change answer changes nothing and is said', async ($, on) => { expect(toasts).toContain('answer not recognised, default kept') }) -test('change: the model question offers the four tiered aliases', async ( +test('change: the model question offers the three tiered aliases', async ( $, on) => { const w = asks(['Change', 'Later']) await bootRun($, on, FABLE, w) await typeFeat($) expect(w.asked[1]?.text).toBe('Which model for feat?') expect(w.asked[1]?.options).toEqual([ - 'fable (best)', 'opus (big)', 'sonnet (work)', 'haiku (cheap)', + 'opus (best)', 'sonnet (work)', 'haiku (cheap)', ]) }) for (const [label, alias, efforts] of [ - ['fable (best)', 'fable', ['medium', 'high', 'xhigh', 'max']], + ['opus (best)', 'opus', ['medium', 'high', 'xhigh', 'max']], ['sonnet (work)', 'sonnet', ['low', 'medium', 'high', 'xhigh']], ] as const) { test(`change: ${alias} offers the efforts of its phases, ascending`, async ( @@ -3074,7 +3095,8 @@ for (const [label, phase] of [ ] as const) { test(`change: ${label} has one effort, the question is skipped`, async ( $, on) => { - const w = asks(['Change', label, 'Later']) + const w = asks(['Change', label, 'Later'], + { legacyTiers: label === 'opus (big)' }) await bootRun($, on, FABLE, w) await typeFeat($) expect(w.asked).toHaveLength(3) @@ -3161,16 +3183,16 @@ test('change: with the switch on the toast carries no hint', async ( test('change: an upgrade toast carries no hint', async ($, on) => { const toasts = recordToasts(on) - const w = asks(['Change', 'fable (best)', 'xhigh', 'Everywhere']) + const w = asks(['Change', 'opus (best)', 'xhigh', 'Everywhere']) await bootRun($, on, SONNET, w) await typeFeat($) - expect(toasts).toContain('/feat now runs claude-fable-5-2 at xhigh') + expect(toasts).toContain('/feat now runs claude-opus-5-5 at xhigh') }) test('change: an upgrade the config holds back carries no hint', async ( $, on) => { const toasts = recordToasts(on) - const w = asks(['Change', 'fable (best)', 'xhigh', 'Everywhere'], + const w = asks(['Change', 'opus (best)', 'xhigh', 'Everywhere'], { home: { mainUpgrade: false } }) await bootRun($, on, SONNET, w) await typeFeat($) @@ -3190,6 +3212,7 @@ test('change: a project scope stores the derived phase, keeps the row', async ( test('change: a security auditor moves to opus at xhigh, at once', async ( $, on) => { const w = asks([...TO_JUDGE, 'Everywhere'], { + legacyTiers: true, edit: f => { (f.agents as Rec)['security-auditor'] = 'verify' }, }) const rig = await bootRun($, on, FABLE, w) @@ -3876,7 +3899,7 @@ test('logs: a route-tool plan logs one line, not one per step', async ( await runStep($, highStep()) await runStep($, highStep()) expect(logs).toEqual([ - mainWord('fable/high', 'fable/xhigh', 'plan: route tool'), + mainWord('fable/high', 'opus/xhigh', 'plan: route tool, switch'), ]) }) @@ -3885,7 +3908,8 @@ test('logs: a typed skill names itself as the cause', async ($, on) => { await typeFeat($) await runStep($, stepInput()) expect(logs).toEqual([ - mainWord('fable/low', 'fable/high', 'reflect: skill /feat'), + mainWord('fable/low', 'opus/high', + 'reflect: skill /feat, switch'), ]) }) @@ -3894,7 +3918,7 @@ test('logs: an upgrade rides on the same line', async ($, on) => { await typeFeat($) await runStep($, { ...highStep(), model: SONNET }) expect(logs).toEqual([ - mainWord('sonnet/high', 'fable/high', 'reflect: skill /feat, upgrade'), + mainWord('sonnet/high', 'opus/high', 'reflect: skill /feat, upgrade'), ]) }) @@ -4007,7 +4031,7 @@ test('logs: the transition line precedes the step below it', async ( await planRoute($) await runStep($, highStep()) expect(logs).toEqual([ - mainWord('fable/high', 'fable/xhigh', 'plan: route tool'), + mainWord('fable/high', 'opus/xhigh', 'plan: route tool, switch'), 'STEP', ]) }) @@ -4053,7 +4077,9 @@ for (const [name, text, act] of LEGACY) { const { logs } = await bootLogged($, on) await act($) await runStep($, highStep()) - expect(logs.filter(l => l.includes(text))).toEqual([]) + // the session on fable moves to opus: its transition line is the new one + expect(logs.filter(l => !l.startsWith('main:') && l.includes(text))) + .toEqual([]) }) } @@ -4169,7 +4195,7 @@ test('logs: one agent type to two models is two hand-offs', async ( test('logs: a tier moved up in-tier names the alias that was down', async ( $, on) => { - const { logs } = await bootLogged($, on) + const { logs } = await bootLogged($, on, { world: legacyWorld() }) await switchTo($, OPUS, SONNET, 'auto') await $.agent.spawn(spawnOf('plan-challenger')) expect(handoffs(logs)).toEqual([ @@ -4522,26 +4548,26 @@ test('residual e: a changed.phases entry is never restored', async ($, on) => { expect(w.written).toEqual([]) }) -/** The efforts the Change chain offers for fable, from the second question. */ -async function fableEfforts($: Engine, on: On, fx: Fixture) { - const w = asks(['Change', 'fable (best)', 'Later'], fx) +/** The efforts the Change chain offers for opus, from the second question. */ +async function opusEfforts($: Engine, on: On, fx: Fixture) { + const w = asks(['Change', 'opus (best)', 'Later'], fx) await bootRun($, on, FABLE, w) await typeFeat($) return w.asked[2]?.options } -const FABLE_EFFORTS = ['medium', 'high', 'xhigh', 'max'] +const OPUS_EFFORTS = ['medium', 'high', 'xhigh', 'max'] test('residual f: a null phase in the file is ignored, no crash', async ( $, on) => { const edit = (f: Rec): void => { (f.phases as Rec).plan = null } - expect(await fableEfforts($, on, { edit })).toEqual(FABLE_EFFORTS) + expect(await opusEfforts($, on, { edit })).toEqual(OPUS_EFFORTS) }) test('residual f: a file without phases offers the code defaults', async ( $, on) => { const edit = (f: Rec): void => { delete f.phases } - expect(await fableEfforts($, on, { edit })).toEqual(FABLE_EFFORTS) + expect(await opusEfforts($, on, { edit })).toEqual(OPUS_EFFORTS) }) const CUSTOM_CHEAP = { phases: { custom: { tier: 'cheap', effort: 'high' } } } @@ -4618,7 +4644,7 @@ test('logs: a hostile skill name is cleaned in the main line', async ( await loadSkill($, HOSTILE_SKILL) await runStep($, { ...highStep(), effort: 'low' as const }) const line = logs.find(l => l.includes('skill /')) ?? '' - const name = nameAfter(line, 'skill /', ')') + const name = nameAfter(line, 'skill /', ')').replace(', switch', '') expect(name).not.toBe('') expect(hasCtrl(line)).toBe(false) expect([...name].length).toBeLessThanOrEqual(40) @@ -5249,7 +5275,7 @@ test('classify visibility: verbose says (reflect: classifier)', async ( await typed($, PLAIN) await runStep($, { ...highStep(), effort: 'low' as const }) expect(c.logs).toContain( - mainWord('fable/low', 'fable/high', 'reflect: classifier')) + mainWord('fable/low', 'opus/high', 'reflect: classifier, switch')) }) test('classify: a repeated undefined label never pauses', async ($, on) => { @@ -5550,8 +5576,8 @@ test('spawn: an upgraded main never pins general-purpose', async ($, on) => { const { rig } = await bootRigVar($, on, HAIKU, 1000) await offerOf($, GP, 'built-in') await planRoute($) - expect((await stepOn($, rig, HAIKU)).model).toBe(FABLE) - await $.agent.spawn(spawnOf(GP, { parentModel: FABLE })) + expect((await stepOn($, rig, HAIKU)).model).toBe(OPUS) + await $.agent.spawn(spawnOf(GP, { parentModel: OPUS })) expect(rig.specs).toEqual([undefined]) }) @@ -5731,7 +5757,7 @@ const downLine = (text: string): string => test('probe: a fable that never answers lands the plan step on opus', async ( $, on) => { - const world = probeWorld(hangsOn(FABLE)) + const world = probeWorld(hangsOn(FABLE), { legacyTiers: true }) const rig = await bootRig($, on, OPUS, 1000, world) // a keyword no longer lifts: the route tool carries the plan tier await pastProbe(rig, planRoute($)) @@ -5756,7 +5782,7 @@ test('probe: the route tool answers an opus id, never fable', async ( }) test('probe: an answered probe is cached across turns', async ($, on) => { - const world = newWorld() + const world = legacyWorld() const rig = await bootRig($, on, OPUS, 1000, world) await planRoute($) expect((await stepOn($, rig, OPUS)).model).toBe(FABLE) @@ -5767,7 +5793,7 @@ test('probe: an answered probe is cached across turns', async ($, on) => { }) test('probe: a lapsed hold probes again and holds longer', async ($, on) => { - const world = probeWorld(hangsOn(FABLE)) + const world = probeWorld(hangsOn(FABLE), { legacyTiers: true }) const rig = await bootRig($, on, OPUS, 1000, world) for (const wait of [15, 30]) { // the route tool lifts, a keyword no longer does @@ -5784,7 +5810,7 @@ test('probe: a lapsed hold probes again and holds longer', async ($, on) => { test('probe: a rejection marks the target down like a timeout', async ( $, on) => { - const world = probeWorld(rejectsOn(FABLE)) + const world = probeWorld(rejectsOn(FABLE), { legacyTiers: true }) const rig = await bootRig($, on, OPUS, 1000, world) await planRoute($) expect((await stepOn($, rig, OPUS)).model).toBe(OPUS) @@ -5796,7 +5822,7 @@ for (const [shape, answer] of [ ['a string', 'ok'], ['an object', PROBE_OK], ['nothing', undefined], ] as const) { test(`probe: ${shape} as the answer lets the move go`, async ($, on) => { - const world = probeWorld(() => answer) + const world = probeWorld(() => answer, { legacyTiers: true }) const rig = await bootRig($, on, OPUS, 1000, world) await planRoute($) expect((await stepOn($, rig, OPUS)).model).toBe(FABLE) @@ -5808,7 +5834,8 @@ test('probe: a failure during the flight keeps the target unverified', async ( $, on) => { let open: () => void = () => undefined const gate = new Promise(resolve => { open = resolve }) - const world = probeWorld(async () => { await gate; return PROBE_OK }) + const world = probeWorld(async () => { await gate; return PROBE_OK }, + { legacyTiers: true }) const rig = await bootRig($, on, OPUS, 1000, world) // the route tool's probe is the one in flight (a keyword no longer lifts) const call = planRoute($) @@ -5876,7 +5903,7 @@ test('probe: a session model that never answers leaves for opus on the first ste test('probe: a healthy session model is probed once and kept', async ( $, on) => { - const world = newWorld() + const world = legacyWorld() const rig = await bootRig($, on, FABLE, 1000, world) await planRoute($) expect((await stepOn($, rig, FABLE)).model).toBe(FABLE) @@ -5904,7 +5931,8 @@ test('probe: a lapsed hold on the session model probes it again', async ( test('probe: false in the override makes no completion at all', async ( $, on) => { - const world = probeWorld(hangsOn(FABLE), { home: { probe: false } }) + const world = probeWorld(hangsOn(FABLE), + { legacyTiers: true, home: { probe: false } }) const rig = await bootRig($, on, OPUS, 1000, world) await planRoute($) expect((await stepOn($, rig, OPUS)).model).toBe(FABLE) @@ -5915,7 +5943,7 @@ test('probe: false in the override makes no completion at all', async ( test('probe: a non-boolean setting is ignored, logged, probe stays on', async ( $, on) => { const logs = recordLogs(on) - const world = newWorld({ home: { probe: 'no' } }) + const world = legacyWorld({ home: { probe: 'no' } }) const rig = await bootRig($, on, OPUS, 1000, world) await planRoute($) await stepOn($, rig, OPUS) @@ -5926,7 +5954,7 @@ test('probe: a non-boolean setting is ignored, logged, probe stays on', async ( test('probe: /clear keeps the verified models', async ($, on) => { on('session.end', ($, e) => ({ sessionId: e.sessionId })) - const world = newWorld() + const world = legacyWorld() const rig = await bootRig($, on, OPUS, 1000, world) await planRoute($) await stepOn($, rig, OPUS) @@ -5946,7 +5974,7 @@ async function fableHeld($: Engine, rig: Rig): Promise { test('stand-in: reflect on opus runs xhigh, and the answer says so', async ( $, on) => { - const rig = await bootRig($, on) + const rig = await bootRig($, on, FABLE, 1000, legacyWorld()) await fableHeld($, rig) const out = await $.tool.call({ tool: ROUTE_TOOL, phase: 'reflect' }) expect(JSON.stringify(out)).toContain( @@ -5956,7 +5984,7 @@ test('stand-in: reflect on opus runs xhigh, and the answer says so', async ( test('stand-in: orchestrate goes medium to high, escalate stays max', async ( $, on) => { - const rig = await bootRig($, on) + const rig = await bootRig($, on, FABLE, 1000, legacyWorld()) await fableHeld($, rig) await $.tool.call({ tool: ROUTE_TOOL, phase: 'orchestrate' }) expect((await stepOn($, rig, FABLE)).effort).toBe('high') @@ -5972,7 +6000,7 @@ test('stand-in: an explicit effort is never bumped', async ($, on) => { }) test('stand-in: fable available, no bump', async ($, on) => { - const rig = await bootRig($, on, OPUS) + const rig = await bootRig($, on, OPUS, 1000, legacyWorld()) await $.tool.call({ tool: ROUTE_TOOL, phase: 'reflect' }) expect(await stepOn($, rig, OPUS)).toEqual({ model: FABLE, effort: 'high' }) }) @@ -6014,7 +6042,7 @@ test('stand-in: an ultrathink floor ends at max, not past it', async ( test('stand-in: the verbose line names it as a cause', async ($, on) => { const logs = recordLogs(on) - const rig = await bootRig($, on) + const rig = await bootRig($, on, FABLE, 1000, legacyWorld()) await route($, 'verbose on') await fableHeld($, rig) await $.tool.call({ tool: ROUTE_TOOL, phase: 'reflect' }) @@ -6048,7 +6076,7 @@ test('keyword cap: ultrathink on an opus session stays on opus at max', async ( test('keyword cap: a route tool call after a keyword still lifts to fable', async ( $, on) => { - const rig = await bootRig($, on, OPUS) + const rig = await bootRig($, on, OPUS, 1000, legacyWorld()) await typed($, 'plan the billing migration') await planRoute($) expect((await stepOn($, rig, OPUS)).model).toBe(FABLE) @@ -6066,7 +6094,7 @@ test('keyword cap: a held fable gives no stand-in notch to a capped keyword', as test('keyword cap: a keyword inside a held best-tier run keeps the run on fable', async ( $, on) => { - const rig = await bootRun($, on, OPUS) + const rig = await bootRun($, on, OPUS, legacyWorld()) await loadSkill($, 'feat') await endTurn($) await typed($, 'plan the next step') @@ -6437,7 +6465,7 @@ for (const scope of ['This conversation', 'This project']) { // ---- bare /model: the router's own dialog --------------------------------- -const STEP1 = ['fable (best)', 'opus (big)', 'sonnet (work)', +const STEP1 = ['fable (custom)', 'opus (best)', 'sonnet (work)', 'Other model (native picker)'] const VARIANTS = ['Standard', '[1m]'] const NO_MODEL = 'model: no model chosen, nothing changed' @@ -6458,7 +6486,7 @@ test('bare model: step 1 lists the table and the native picker', async ( test('bare model: opus, [1m], This project writes the full id', async ( $, on) => { const m = await bootModel($, on, - ['opus (big)', '[1m]', 'This project']) + ['opus (best)', '[1m]', 'This project']) await modelCmd($, '') expect(m.w.asked.map(q => q.options)).toEqual([STEP1, VARIANTS, SCOPES]) const variant = m.w.asked[1] as Asked @@ -6469,7 +6497,7 @@ test('bare model: opus, [1m], This project writes the full id', async ( test('bare model: the current model asks its scope too', async ($, on) => { const m = await bootModel($, on, - ['opus (big)', 'Standard', 'This conversation']) + ['opus (best)', 'Standard', 'This conversation']) expect(await modelCmd($, '')).toContain(`sticky route ${OPUS}`) expect(m.w.asked).toHaveLength(3) expect(m.ran).toEqual([]) @@ -6525,7 +6553,7 @@ test('bare model: Everywhere runs native with the token', async ($, on) => { test('bare model: [1m] with This conversation carries the note', async ( $, on) => { - await bootModel($, on, ['fable (best)', '[1m]', 'This conversation']) + await bootModel($, on, ['fable (custom)', '[1m]', 'This conversation']) expect(await modelCmd($, '')).toContain("[1m] follows the session's variant") }) @@ -6951,9 +6979,12 @@ const INSTEAD = 'Opus instead (big tier)' const STOP = 'Stop asking this session' const TIER_OPTIONS = ['Fable', INSTEAD, STOP] -/** A world with the tier ask on; the first-use `ask` stays off. */ +/** + * A world with the tier ask on; the first-use `ask` stays off. The ask only + * runs when fable heads best: an override puts it back (LEGACY tiers). + */ const asksTier = (answers: string[], fx: Fixture = {}) => - newWorld({ answers, askTier: 'best', ...fx }) + newWorld({ answers, askTier: 'best', legacyTiers: true, ...fx }) /** An extra skill row, for the tests that need a second typed skill. */ const withRows = (rows: Table) => (file: Rec): void => { @@ -7178,6 +7209,18 @@ test('TIER: a rowed spawn asks once per type; Opus instead sticks', async ( expect(rig.specs).toEqual([OPUS, OPUS]) }) +test('TIER: ask-tier off keeps an Opus instead answer on opus', async ( + $, on) => { + const w = asksTier([INSTEAD, INSTEAD], { edit: auditVerifier }) + const rig = await bootRun($, on, OPUS, w) + await typeFeat($) + await $.agent.spawn(spawnOf('verifier')) + expect(await route($, 'ask-tier off')).toBe('ask-tier off') + expect(await lastStep($, rig)).toEqual({ model: OPUS, effort: 'high' }) + await $.agent.spawn(spawnOf('verifier')) + expect(rig.specs).toEqual([OPUS, OPUS]) +}) + test('TIER: Fable on a spawn runs the head', async ($, on) => { const rig = await bootRun($, on, OPUS, asksTier(['Fable'], { edit: auditVerifier, @@ -7199,7 +7242,7 @@ test('TIER: an explicit model, a nested spawn and a work row never ask', async ( test('TIER: the first-use dialog runs first, then the tier ask', async ( $, on) => { - const w = asks(['Keep', INSTEAD], { askTier: 'best' }) + const w = asks(['Keep', INSTEAD], { legacyTiers: true, askTier: 'best' }) const rig = await bootRun($, on, OPUS, w) await typeFeat($) expect(w.asked).toHaveLength(2) @@ -7210,7 +7253,8 @@ test('TIER: the first-use dialog runs first, then the tier ask', async ( test('TIER: a stored spawn answer holds while another dialog is open', async ( $, on) => { - const w = asks(['Keep', INSTEAD], { askTier: 'best', edit: auditVerifier }) + const w = asks(['Keep', INSTEAD], + { legacyTiers: true, askTier: 'best', edit: auditVerifier }) const rig = await bootRun($, on, OPUS, w) await $.agent.spawn(spawnOf('verifier')) const hold = deferred() @@ -7228,7 +7272,7 @@ test('TIER: a stored spawn answer holds while another dialog is open', async ( }) test('TIER: a dialog in flight routes a typed skill unasked', async ($, on) => { - const w = asks(['Keep'], { askTier: 'best' }) + const w = asks(['Keep'], { legacyTiers: true, askTier: 'best' }) const hold = deferred() const open = deferred() w.gate = hold.gate @@ -7290,6 +7334,130 @@ test('TIER: no routing.json means no ask; the route is set', async ($, on) => { expect(mainLine(await route($, 'show'))).toContain('model plan') }) +// ---- SHIPPED tiers: fable is ranked, never an auto-route target ---------- +// No override here: best and big are [opus, sonnet]. A machine override can +// put fable back (the TIER section above runs on those LEGACY tiers). + +const routeTo = (phase: string) => (file: Rec): void => { + (file.skills as Table).feat = phase + ;(file.agents as Table).feater = phase +} + +for (const phase of ['plan', 'judge', 'audit']) { + test(`shipped: a typed ${phase} row routes main to opus`, async ( + $, on) => { + const rig = await bootRun($, on, OPUS, newWorld({ edit: routeTo(phase) })) + await typeFeat($) + expect((await lastStep($, rig)).model).toBe(OPUS) + }) + + test(`shipped: a ${phase} agent row spawns on opus`, async ($, on) => { + const rig = await bootRun($, on, OPUS, newWorld({ edit: routeTo(phase) })) + await $.agent.spawn(spawnOf('feater')) + expect(rig.specs).toEqual([OPUS]) + }) +} + +test('shipped: with opus down best and big never choose fable', async ( + $, on) => { + const logs = recordLogs(on) + const w = newWorld({ edit: auditVerifier }) + const rig = await bootRun($, on, OPUS, w) + await switchTo($, OPUS, SONNET, 'auto') + await planRoute($) + expect((await stepOn($, rig, SONNET)).model).toBe(SONNET) + await $.agent.spawn(spawnOf('plan-challenger')) + await $.agent.spawn(spawnOf('verifier')) + // the frontmatter floor runs: no model is chosen, fable least of all + expect(rig.specs).toEqual([undefined, undefined]) + expect(logs).toContain( + 'model-router: plan-challenger tier big down, frontmatter model kept') + expect(logs).toContain( + 'model-router: verifier tier best down, frontmatter model kept') +}) + +test('shipped: a hand-picked fable ranks above opus, a limit leaves it', async ( + $, on) => { + const h = await bootHand($, on, ['This conversation']) + await modelCmd($, 'fable') + expect((await stepOn($, h.rig, OPUS)).model).toBe(FABLE) + await failWith($, 'rate_limit') + expect((await stepOn($, h.rig, FABLE)).model).toBe(OPUS) +}) + +test('shipped: boot and reload log no "does not lead" line', async ( + $, on) => { + const logs = recordLogs(on) + await bootRun($, on, OPUS) + await route($, 'reload') + expect(logs.filter(l => l.includes('does not lead'))).toEqual([]) +}) + +/** The machine override turns the tier ask on: best is still not fable's. */ +const askOn = (answers: string[], edit?: (file: Rec) => void): World => + newWorld({ answers, home: { askTier: 'best' }, ...(edit ? { edit } : {}) }) + +test('shipped: an audit spawn asks no tier question, the answer stays', async ( + $, on) => { + const w = askOn([INSTEAD], auditVerifier) + const rig = await bootRun($, on, OPUS, w) + await $.agent.spawn(spawnOf('verifier')) + expect(w.asked).toEqual([]) + expect(w.answers).toEqual([INSTEAD]) + expect(rig.specs).toEqual([OPUS]) +}) + +test('shipped: a best row typed from sonnet asks nothing, main on opus', async ( + $, on) => { + const w = askOn([INSTEAD]) + const rig = await bootRun($, on, SONNET, w) + await typeFeat($) + expect(w.asked).toEqual([]) + expect((await lastStep($, rig, SONNET)).model).toBe(OPUS) +}) + +test('shipped: /route ask-tier on says inert, show says inert', async ( + $, on) => { + await bootRun($, on, OPUS, newWorld()) + expect(await route($, 'show')).toContain('ask-tier: off') + expect(await route($, 'ask-tier on')) + .toBe('ask-tier on (inert: best is not headed by fable)') + expect(await route($, 'show')).toContain('ask-tier: inert') + expect(await route($, 'ask-tier off')).toBe('ask-tier off') +}) + +test('legacy: an override heading best and big with fable asks', async ( + $, on) => { + const both = ['fable', 'opus', 'sonnet'] + const w = asksTier([INSTEAD], { + home: { tiers: { best: both, big: both } }, + }) + await bootRun($, on, OPUS, w) + await typeFeat($) + expect(w.asked).toHaveLength(1) + expect(w.asked[0]?.text).toContain('Run it on fable?') +}) + +test('shipped: the Change dialog offers no fable, judge stays judge', async ( + $, on) => { + const w = asks(['Change', 'opus (best)', 'xhigh', 'Everywhere']) + await bootRun($, on, OPUS, w) + await $.agent.spawn(spawnOf('plan-challenger')) + expect(w.asked[1]?.text).toBe('Which model for plan-challenger?') + expect(w.asked[1]?.options).toEqual([ + 'opus (best)', 'sonnet (work)', 'haiku (cheap)', + ]) + expect((routingOf(w).agents as Rec)['plan-challenger']).toBe('judge') +}) + +test('shipped: the bare model dialog still offers fable, as custom', async ( + $, on) => { + const m = await bootModel($, on, []) + await modelCmd($, '') + expect(m.w.asked[0]?.options).toContain('fable (custom)') + expect(m.w.asked[0]?.options).toEqual(STEP1) +}) + // ---- GUARD: main-loop code writes go through a skill -------------------- const GUARD = 'model-router: code is written inside a skill run.' diff --git a/mods/model-router/hooks/register.ts b/mods/model-router/hooks/register.ts index 112c605..721d3ec 100644 --- a/mods/model-router/hooks/register.ts +++ b/mods/model-router/hooks/register.ts @@ -204,7 +204,11 @@ const KEEP = 'Keep' const CHANGE = 'Change' const EVERYWHERE = 'Everywhere' // Tier ask: the answers; INSTEAD_TIER is the tier "Opus instead" resolves by. +// shortcut: the ask-before-Fable dialog only runs when an override heads +// `best` with fable (BLK-030 credit guard), hence the hardcoded label; remove +// the feature if Fable never returns to a tier. const TIER_HEAD = 'Fable' +const TIER_HEAD_ALIAS = 'fable' const TIER_INSTEAD = 'Opus instead (big tier)' const TIER_STOP = 'Stop asking this session' const INSTEAD_TIER = 'big' @@ -223,7 +227,7 @@ const BARE_ALIASES: readonly string[] = ['fable', 'opus', 'sonnet'] const STANDARD = 'Standard' const LONG = '[1m]' const LOCAL_SETTINGS = '.claude/settings.local.json' -const CHOICE_ALIASES: readonly string[] = ['fable', 'opus', 'sonnet', 'haiku'] +const CHOICE_ALIASES: readonly string[] = ['opus', 'sonnet', 'haiku'] const MAX_DESC = 140 // chars of a skill or agent description in a question const MAX_ABOUT = 120 // chars of a phase `about` const MAX_DESCS = 256 // agent descriptions kept (oldest dropped) @@ -294,10 +298,12 @@ const DEFAULT_CONFIG: Config = { fable: 'claude-fable-5-2', }, windows: {}, - // A tier is an ordered alias list: the first one not down is used. + // A tier is an ordered alias list: the first one not down is used. Fable is + // ranked (hand picks, the advisor model) but never an auto-route target + // (user 2026-11-16); a machine override may put it back in a tier. tiers: { - best: ['fable', 'opus', 'sonnet'], - big: ['opus', 'fable', 'sonnet'], + best: ['opus', 'sonnet'], + big: ['opus', 'sonnet'], work: ['sonnet', 'opus'], cheap: ['haiku', 'sonnet'], }, @@ -615,10 +621,6 @@ function mergeRouting( const tiers = mergeTable( base.tiers, user.tiers, 'tiers', acceptTier(models, log), log) const fallback = pickFallback(user.fallback, base.fallback, models, log) - if (tiers.best?.[0] !== fallback[0]) { - log('model-router: tiers.best does not lead the fallback chain; rank ' + - 'comes from the fallback list alone') - } return { tiers, fallback, @@ -1148,7 +1150,7 @@ function availableIn(st: State, aliases: readonly string[]) { function nextAvailable(st: State, after: string | undefined) { const { fallback, models } = st.cfg const at = fallback.findIndex(alias => models[alias] === after) - return availableIn(st, fallback.slice(at + 1)) + return at < 0 ? undefined : availableIn(st, fallback.slice(at + 1)) } /** @@ -1171,14 +1173,27 @@ function headId(st: State): string | undefined { return alias === undefined ? undefined : st.cfg.models[alias] } +/** The ask-before-Fable dialog is fable-specific: best must be headed by it. */ +function fableHeadsBest(st: State): boolean { + const list = hasKey(st.cfg.tiers, BEST) ? st.cfg.tiers[BEST] : undefined + return list?.[0] === TIER_HEAD_ALIAS +} + /** * The head a route is asked about before it applies; undefined = off. The * machine override wins; an absent key reads best, so does any other value - * (asking is the safe side, `warnAskTier` says so once). + * (asking is the safe side, `warnAskTier` says so once). Inert (undefined) + * unless the head of `best` is fable. */ function tierHead(st: State): string | undefined { const value = st.mem.askTierLocal ?? st.mem.askTier - return value === false ? undefined : headId(st) + return value === false || !fableHeadsBest(st) ? undefined : headId(st) +} + +/** The ask is on by config but best is not headed by fable: nothing asks. */ +function tierInert(st: State): boolean { + const value = st.mem.askTierLocal ?? st.mem.askTier + return value !== false && !fableHeadsBest(st) } /** The `big` tier's models, the head left out, in order. */ @@ -1605,7 +1620,8 @@ type Verdict = { */ function wantedModel(st: State, cur: string): string | undefined { const slot = mainModelSlot(st) - const instead = slot?.tierChoice === 'big' && slot.route.tier === BEST + const instead = slot?.tierChoice === 'big' && slot.route.tier === BEST && + fableHeadsBest(st) const name = instead ? insteadName(st) ?? routeName(slot.route) : routeName(slot?.route) if (name === undefined) return undefined @@ -1992,6 +2008,7 @@ async function snapshot($: Api, st: State) { /** `/route show`: the tier ask's state, a Stop answer included. */ function askTierWord(st: State): string { + if (tierInert(st)) return 'inert' if (tierHead(st) === undefined) return 'off' return st.tierPaused ? 'best (paused this session)' : BEST } @@ -2799,7 +2816,7 @@ function headAlias(cfg: Config, route: Route): string | undefined { : aliasOf(cfg, canonical(cfg, route.model)) } -/** "fable (best)": the alias and the tier it heads ("custom" if none). */ +/** "opus (best)": the alias and the tier it heads ("custom" if none). */ function modelLabel(cfg: Config, alias: string): string { const tier = Object.keys(cfg.tiers).find(t => cfg.tiers[t]?.[0] === alias) return `${alias} (${tier ?? 'custom'})` @@ -3244,7 +3261,9 @@ async function spawnTier( ) { if (route === undefined || route.tier !== BEST) return route if (!st.tierSpawn.has(e.subagentType)) await spawnTierAsk($, st, e, route) - return st.tierSpawn.get(e.subagentType) === 'big' + const instead = st.tierSpawn.get(e.subagentType) === 'big' && + fableHeadsBest(st) + return instead ? insteadRoute(st, route) : route } @@ -3309,7 +3328,9 @@ async function flagCommand( const local = flag.local(st.mem) const note = local === undefined ? '' : `; ~/${OVERRIDE} sets ${key} ${ local === false ? 'off' : 'on'} and wins here` - return `${word} ${arg}${note}` + const inert = flag === ASK_TIER_FLAG && arg === 'on' && tierInert(st) + return `${word} ${arg}${note}${ + inert ? ' (inert: best is not headed by fable)' : ''}` } // ---- /route forget: the user takes decisions back ------------------------- From 42385d2936dd0c0a6a66ff24ba44cab717c03226 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 16 Nov 2026 23:04:48 +0100 Subject: [PATCH 2/3] docs: router routes no Fable, Opus heads best and big; changelog --- CHANGELOG.md | 3 ++- README.md | 30 ++++++++++++++++-------------- USAGE.md | 2 +- 3 files changed, 19 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d32f0d3..bc25ccd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,10 +15,11 @@ The BDR-125 context queue is delivered: phases 0, 0b, 4a, 1, 5, 2 and 4b-4d ship - **memory recall**: a prompt after 30 minutes idle now needs 8 content words, up from 5 (a context's first prompt or a design/analysis prompt still needs 5), and the haiku rerank keeps at most 2 entries, down from 3. Measured on the first feedback gate: idle precision 44 %, third pick 35 %. - **memory digest TODO lines**: with no `## Actionable` (or `### Actionable`) section, the digest now shows the TODO file's first 3 unchecked top-level items instead of none, and items inside HTML comments are ignored. When the 800-character cap drops TODO lines, a `- todo: +N not shown, read .claude/tasks/TODO.md` line counts them. `/init-project`, `/onboard` and `/capitalize` seed new TODO files with a `## Actionable` section. The session-start doctrine (`CLAUDE.global.md`) now trusts the digest and reads `.claude/tasks/TODO.md` only when no digest prints or the task needs it. - **Skill routing (`CLAUDE.global.md`)**: routing lines a skill's own description already covers move there (bugfix, feat/hotfix split, ship-feature, tour, reconcile, capitalize, close); the section keeps the gstack cases (investigate on explicit ask, gstack ship retired per BDR-105), the pack-off SEO/GEO/W3C line (`profile.sh enable seo|web-validate`), `cso` and media. `/bugfix` triggers gain "error", "500", "stack trace + fix"; `/ship-feature` gains "ship this feature". -- **model-router**: the `fable` alias, head of the best tier, resolves to `claude-fable-5-2` (was `claude-fable-5-1`); every best-tier phase, row and skill pin naming `fable` follows. Kit tests updated. +- **model-router**: the `fable` alias resolves to `claude-fable-5-2` (was `claude-fable-5-1`); every phase, row and skill pin naming `fable` follows. Kit tests updated. - **memory feedback**: precision, trigger precision and the miss share count only rows after the gate-1 fix (merge 2026-11-12T19:53:59Z); their actions wait for 20 post-fix asks (`Post-fix prompt asks: k/20` in FEEDBACK.md, one `NEW: post-fix prompt sample reached` line) and the session reminder keeps prompting until then. The third-pick signal is retired (recall keeps 2 picks). The reader holds one parsed transcript at a time; `labels.tsv` rows and `state.json` are validated on read. - **memory commit chokepoint**: `lib/memory.sh check --staged`, run by `lib/memory-commit.sh commit` before every memory commit (rc 6, registry unstaged), also refuses a staged v2 registry whose new `## ` entry does not carry the next free ID: the highest ID seen at any heading level, fenced or not, in HEAD and above the entry in the staged file, plus one, the same reading `add` uses. stderr: `memory: :: new entry is not the next free ID -NNN`. A committed ID is never renamed: fix the uncommitted heading and every uncommitted mention of its ID (the `superseded by` line from `add --supersedes`, the journal line), or drop the new entry and re-add it with `memory.sh add`. Skipped when the registry is absent from HEAD, HEAD is v1 (an `upgrade` commit), HEAD has an open code fence, or HEAD has no well-formed `## ` entry. Tests: `lib/tests/memory.test.sh`. - **model-router write guard fails closed**: when the guard's own check throws or times out, a main-loop Edit, Write or NotebookEdit of a code file outside a skill run is held with `model-router: the write guard failed (), so this write is held. Enter /hotfix, /feat, /bugfix or /ship-feature, or re-enter the skill you were running, then make this edit.` One log line per session: `model-router: write guard failed (): main-loop code writes are held until a skill runs`. Sub-agents, skill runs (typed, model-declared phase, typed `/route`) and `.md` / `.txt` files still pass; an error raised by a downstream tool is replayed as before. The guard used to let the write through on its own failure. Tests: `mods/model-router/hooks/register.test.ts` (GUARD: a failing guard …). +- **model-router: Fable leaves auto-routing**: the `best` and `big` tiers default to opus then sonnet (were fable>opus>sonnet and opus>fable>sonnet), so Opus is the strongest model the router routes to and Fable is the advisor (`advisorModel` in settings.json). Fable stays in the model table and first in the fallback rank, so a hand pick of fable ranks above opus. The first-use Change dialog offers opus, sonnet and haiku; the bare `/model` dialog still offers fable, labelled `fable (custom)`. The ask before Fable only fires when a machine override puts fable at the head of `best`: otherwise `/route ask-tier on` answers `(inert: best is not headed by fable)` and `/route show` prints `ask-tier: inert`. An agent on a best or big row keeps its opus frontmatter when Opus is down. The `tiers.best does not lead the fallback chain` log is gone; `routing.json` is unchanged. Tests: `mods/model-router/hooks/register.test.ts`; `lib/tests/effort-routing.test.sh` floors every row on its tier's head. ### Removed - `hooks/design-toolchain-reminder.sh`, its `UserPromptSubmit` entry in `settings.json` (`ctx7-reminder` stays the only one) and its suite `lib/tests/design-toolchain-reminder.test.sh`. Measured 2026-10-31: 59 fires, 0 Reads of `rules/web-building.md`. Design routing stays with the `rules/web-building.md` path rule and the `CLAUDE.global.md` pointer. The fire log `~/.claude/logs/design-toolchain-fires.log` is left in place. diff --git a/README.md b/README.md index 63bcb31..071a4b3 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ Not a collection of prompts — an operating layer on top of Claude Code: full feature pipeline with validation gates. - **Agents** are the execution units skills dispatch to — each pinned to the cheapest model that can do the job (haiku collects, sonnet executes, - opus judges and runs the session, Fable plans and runs the merge gates). + opus judges, plans and runs the session and the merge gates; Fable is the advisor). - **Hooks and permissions** are deterministic guardrails: gitflow enforced by a pre-commit hook in every repo (`make link` points git's global `core.hooksPath` at `~/.claude/githooks`), every commit pushed by @@ -71,8 +71,10 @@ commands, settings, secrets, maintenance. ## Agent model routing (model-tiering v2) Doctrine: the main loop runs on the `opus` session model; the model-router rows -lift it to Fable for main-loop reflection ONLY: brainstorm, plan, contract, -audit judgment, loop decisions. The main loop writes no code outside a skill run (the router's guard +route main-loop reflection (brainstorm, plan, contract, +audit judgment, loop decisions) to the `best` tier, opus at the phase's effort. +Fable is never auto-routed: it is the advisor (`advisorModel` in settings.json) +and a hand pick. The main loop writes no code outside a skill run (the router's guard redirects it to a skill); the fresh gates run as dispatched agents on the `audit` row. The Fable/Opus model floor is enforced by a blocking gate (`lib/model-gate.md`) at the entry of the 17 reflection skills (the orchestrators, `/analyze`, @@ -87,8 +89,8 @@ model-router row, their | Agent | Model | Tier | |---|---|---| | feater, hotfixer, bugfixer | sonnet (pinned) | executors — code from a closed plan (feat), fix from a closed diagnosis (bugfix), fix-bundle appliers | -| verifier | Fable (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) | -| security-auditor | Fable (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) | +| verifier | opus (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) | +| security-auditor | opus (`audit` row: best/xhigh, opus frontmatter floor) | fresh gate (≤3×/loop) | | commit-changer, release-executor, code-cleaner | sonnet (pinned) | dispatched execution — grouping+commit / release prep span / approved cleanup (audit + approval gates stay in the dispatcher) | | onboarder, scaffolder, refactorer, validator-analyzer, plugin-probe | sonnet (pinned) | workers — config generation, scaffold, refactor, deterministic W3C/WCAG runner, mechanical plugin probe | | status-reporter | haiku (pinned) | mechanical collector | @@ -117,8 +119,8 @@ and agent, each phase naming a tier and an effort level work/high, `verify` work/xhigh, `explore` work/medium, `apply` work/low, `mechanical` cheap/low). The `model:` and `effort:` frontmatter of every typed agent and user-invoked skill stays as the off-state floor, kept equal -to the rows by the census `lib/tests/effort-routing.test.sh` (a best-tier -row floors on the tier's second alias, opus, since Fable is credit-gated; a +to the rows by the census `lib/tests/effort-routing.test.sh` (a row's model +floor is its tier's head, opus for `best` and `big`; a row changed through the first-use dialog passes with a `WARN floor drift` line until its frontmatter follows): low appliers, medium executors, high writers, xhigh judgment and gates; @@ -137,19 +139,19 @@ effort, never version. Transcript audit `python3 lib/effort-audit.py`. `mods/model-router/` is a Claude Code mod (a function-hooks plugin) that applies this table per request. It loads in every session through the tracked symlink `skills/model-router`, as `model-router@skills-dir`. -- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`; `audit` is an agent row, never typed) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` (typed with a name, bare, or picked in the `/model` picker, it asks the scope: this project, this conversation, everywhere) or a typed skill on a non-best row. A skill without a row leaves the route as it is. A rowed skill the model loads inside a best-tier run moves effort only when its row ranks below the run's model. Main routed onto a model whose context window the conversation outgrew returns to the session model. Before main runs on a model, the one it moves to or the one it keeps (the session's own model included), the mod probes it with one small completion bounded to 8 seconds; the step (and `/route show`, the route tool's answer) waits for it. A timeout or an error marks the model down (reason `probe`, held for `cooldownMinutes` like any breaker hold) and the decision is taken again once. A model already marked down is never probed, and a model that answered is not probed again, `/clear` included, until it is marked down. When a lower model stands in for its tier's head held down (Opus for Fable on a best-tier phase), the phase's own effort goes one notch up: `reflect` xhigh, `plan` max, `orchestrate` high, `escalate` stays max. An effort asked explicitly (`/route ... effort=`, the `route` tool's `effort`) or set by a floor is never raised. `/route show` and the route tool's answer print the level with `(opus stands in for fable)`; the verbose transition line names `stand-in` as a cause. +- Main loop: every request gets the route in force. A typed skill with a row routes the main loop to it; a best-tier row (`plan`, `reflect`, `orchestrate`, `escalate`; `audit` is an agent row, never typed) holds across turns in a run slot until `/route clear`, `/route off`, a user `/model` (typed with a name, bare, or picked in the `/model` picker, it asks the scope: this project, this conversation, everywhere) or a typed skill on a non-best row. A skill without a row leaves the route as it is. A rowed skill the model loads inside a best-tier run moves effort only when its row ranks below the run's model. Main routed onto a model whose context window the conversation outgrew returns to the session model. Before main runs on a model, the one it moves to or the one it keeps (the session's own model included), the mod probes it with one small completion bounded to 8 seconds; the step (and `/route show`, the route tool's answer) waits for it. A timeout or an error marks the model down (reason `probe`, held for `cooldownMinutes` like any breaker hold) and the decision is taken again once. A model already marked down is never probed, and a model that answered is not probed again, `/clear` included, until it is marked down. When a lower model stands in for its tier's head held down (Sonnet for Opus on a best-tier phase; Opus for Fable when a machine override heads `best` with fable), the phase's own effort goes one notch up: `reflect` xhigh, `plan` max, `orchestrate` high, `escalate` stays max. An effort asked explicitly (`/route ... effort=`, the `route` tool's `effort`) or set by a floor is never raised. `/route show` and the route tool's answer print the level with `( stands in for )`, `(sonnet stands in for opus)` with the shipped tiers; the verbose transition line names `stand-in` as a cause. - Sub-agents: a routed agent gets its row's model at spawn, within its tier and only upward from its frontmatter model, and the row's effort on every step. Explicit `model` / `effort` params on the Agent call win; a project-defined agent of the same name keeps its own definition. Built-ins: Explore runs on sonnet/medium, Plan on opus/xhigh. A built-in `general-purpose` agent that main spawns with no `model` param, while main runs below the session model (a downgrade or a breaker fallback), starts on the session model instead of inheriting the lower one; it is not pinned when the session model is marked down, for a fork, a workflow or a nested spawn, or when a project or user definition shadows the built-in. Other agent types are never pinned this way: the hook cannot see their frontmatter model. - Write guard: a main-loop Edit, Write or NotebookEdit of a code file is redirected with "model-router: code is written inside a skill run…" until a skill ran on the main loop in the session (typed or loaded by the model; a refused or unknown skill does not count), a phase was declared this turn, or a typed `/route` holds. Free paths: `.md`, `.txt`, the project's `.claude/` except `worktrees/`, and `docs/`. Sub-agents write freely. If the guard's own check fails (throw or timeout), it holds such a write instead of letting it through, with "model-router: the write guard failed (), so this write is held…", logged once per session; sub-agents, a skill run, a declared phase or a typed `/route`, and `.md` / `.txt` files still pass, and an error raised by the tool itself is passed on unchanged. `/route clear`, `/route off` and `/clear` re-arm the guard; `/route off` also turns it off, and `"enabled": false` in `~/.claude/model-router.json` turns the router and the guard off. A `/model` hand pick does not open it, and a `register.ts` reload resets it. -- Levers inside a run: `ultrathink` in a prompt sets the turn's minimum effort; `/route effort=max` holds until `/route clear`. Keyword prompt rules (`plan`, `design`, `architecture`… take plan's effort; `why`, `review`, `audit`… reflect's), `ultrathink` and a main Agent dispatch (the derived `orchestrate` route, held until its background agents end) set the turn's effort only, never a model: they never lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a skill row, the `route` tool, a typed `/route` or a hand pick (`/model`, picker). The built-in `/effort` is not a lever inside a run, rows and routes outrank it. -- `/model` scope: a pick in the `/model` picker is held first (the engine prints that a hook blocked it), then the same question as `/model ` comes. A bare `/model` opens the router's model, variant and scope dialog: fable, opus or sonnet, then Standard or `[1m]`, then the scope, the current model included; `Other model (native picker)` opens the native picker (haiku goes through it or `/model haiku`) and Esc changes nothing. A pick while another dialog is open is refused with `answer the open dialog first`. The picker's Default, an unknown name or a headless run go native, no question. A model chosen in that dialog (a hand pick) always switches: no cold-read cap, no `mainUpgrade` or `mainModelSwitch` flag. A hand pick marked down keeps main where it is until it is back. A native switch (the `/config` Model row included) or `/clear` drops a hand pick; a typed `/route model=` keeps the caps. +- Levers inside a run: `ultrathink` in a prompt sets the turn's minimum effort; `/route effort=max` holds until `/route clear`. Keyword prompt rules (`plan`, `design`, `architecture`… take plan's effort; `why`, `review`, `audit`… reflect's), `ultrathink` and a main Agent dispatch (the derived `orchestrate` route, held until its background agents end) set the turn's effort only, never a model: they never lift main above the session model, and a held best-tier run keeps its model. Fable on main comes only from a hand pick (`/model`, picker), a typed `/route model=fable` or a machine override that puts fable in a tier: no shipped tier holds it. The built-in `/effort` is not a lever inside a run, rows and routes outrank it. +- `/model` scope: a pick in the `/model` picker is held first (the engine prints that a hook blocked it), then the same question as `/model ` comes. A bare `/model` opens the router's model, variant and scope dialog: fable (labelled `fable (custom)`, it heads no shipped tier), opus or sonnet, then Standard or `[1m]`, then the scope, the current model included; `Other model (native picker)` opens the native picker (haiku goes through it or `/model haiku`) and Esc changes nothing. A pick while another dialog is open is refused with `answer the open dialog first`. The picker's Default, an unknown name or a headless run go native, no question. A model chosen in that dialog (a hand pick) always switches: no cold-read cap, no `mainUpgrade` or `mainModelSwitch` flag. A hand pick marked down keeps main where it is until it is back. A native switch (the `/config` Model row included) or `/clear` drops a hand pick; a typed `/route model=` keeps the caps. - Prompt classifier: a plain prompt typed in the composer (12 characters or more, not a slash command) that no keyword rule, skill, run slot, `/route` or floor covers is sent to the engine's small fast model, one call, bounded to 3 seconds (the prompt waits for it, typically under a second). The label (`design`, `analysis`, `coding`, `bookkeeping`, `chat`) maps to plan, reflect, implement or apply (`chat` routes nothing), and the turn takes that phase's route: its effort becomes the turn's default, and its model may move the main loop, never above the session model. A `coding` or `bookkeeping` guess moves main down only when `mainModelSwitch` is on and the cold read fits `downgradeMaxTokens`; an `ultrathink` floor in the same turn raises the effort only, the guess's model holds. No dialog opens and no file is written. The route is gone at the end of the turn, a later route call or typed skill replaces it, and a `/effort` you type between turns drops the guess for that turn only. A typed best-tier skill holds its run slot across turns, so nothing is classified there until `/route clear`. Long prompts are sampled (first 500 and last 1500 code points), so pasted text at the end can steer one turn's route. Three failures in a row pause it for `cooldownMinutes` (one toast, `classifier: paused` in the status line). Never in a sub-agent, mid-turn or under `-p`. Off per session with `/route classify off`, per machine with `"classify": false`. The status line reads `route: classifier `; `/route verbose on` adds the transition line. -- `/route` (user command) shows or sets the route: `show`, `clear`, `off`, `on`, `reload`, `pending` (rows and phases not confirmed yet), `ask on|off` (first-use dialog on or off), `ask-tier on|off` (the ask before Fable, below), `forget ` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model= effort=`, `switch on|off`, `classify on|off` (the prompt classifier, below), `verbose on|off` (logs transitions only: each change of model or effort, with a few words of cause). `/route show` names the run slot when one holds (`main: run `) and prints the switch with its cap and the prompt-cache TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`) and `ask-tier:` (`best`, `best (paused this session)` or `off`). The model sets routes through a `route` tool. -- First use: the first time a rowed skill is typed, a rowed agent is spawned or a phase is declared on the main loop through the `route` tool, the mod asks once whether the route is right. The question gives context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line, and the model id and effort the next step really runs on; a declared phase also says what uses it (rows, prompt rules). A row offers Later, Keep or Change; a declared phase offers Later or Keep. Change asks the model (fable, opus, sonnet, haiku, each shown with the tier it heads), then the effort among those the phases on that model use (shipped table: fable medium, high, xhigh or max; sonnet low, medium, high or xhigh; opus and haiku have one level each, so no question), then Everywhere or This project only. Rows stay phase names, so the pair maps to an existing phase: the row's current phase wins a tie and the same phase counts as Keep; a pair no phase offers needs a new phase added by hand in routing.json. Everywhere moves the row and records the shipped phase under `changed`; This project only stores an exception under `projects`, keyed by the origin remote reduced to `host/path` (no credentials, no local paths; a remote that cannot be read that way offers no project choice). Keep lands under `confirmed`; Later, a dismissed dialog or a free-text answer asks again next session. After a skill row changes, a toast names the model and effort that skill now runs on, plus a hint when the main loop holds back a downgrade: `/route switch on` when the switch is off, the cap hold (`held: downgrade skipped: cold read tokens over `) when the cold read is over `downgradeMaxTokens`. One dialog at a time, never in a headless (`-p`) run, never inside a sub-agent. -- Ask before Fable: before a route lifts the main loop, or sends a rowed agent, onto Fable from another model, the mod asks once per span. The question names the origin (a skill, typed or loaded by the model, an agent, the `route` tool or `/route`), the phase with its `about` line, and the model and effort the step would run on. `Fable` runs it; `Opus instead (big tier)` runs the span through the `big` tier at the phase's own effort, offered only while Opus is up so the label stays true; `Stop asking this session` pauses the question until `/clear`. A best-tier skill the model loads counts as a skill row, and an agent type gets one answer per session. Nothing is asked in a headless (`-p`) run or inside a sub-agent, a dismissed dialog runs Fable, and no answer is written (`confirmed` included). No question comes when the decision would not land on Fable (`mainUpgrade` off, a cold-read cap, the context window, Fable marked down); when such a Fable hold or cap lapses later, main upgrades without asking, as the breaker already does. `askTier` in routing.json (`best`, or `false` to turn it off) is set by `/route ask-tier on|off`, and the machine config wins. +- `/route` (user command) shows or sets the route: `show`, `clear`, `off`, `on`, `reload`, `pending` (rows and phases not confirmed yet), `ask on|off` (first-use dialog on or off), `ask-tier on|off` (the ask before Fable, below), `forget ` (takes decisions back: a changed row returns to its shipped phase; `all` and `projects` ask first), a phase name, `model= effort=`, `switch on|off`, `classify on|off` (the prompt classifier, below), `verbose on|off` (logs transitions only: each change of model or effort, with a few words of cause). `/route show` names the run slot when one holds (`main: run `) and prints the switch with its cap and the prompt-cache TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`) and `ask-tier:` (`best`, `best (paused this session)`, `off`, or `inert` while `best` is not headed by fable). The model sets routes through a `route` tool. +- First use: the first time a rowed skill is typed, a rowed agent is spawned or a phase is declared on the main loop through the `route` tool, the mod asks once whether the route is right. The question gives context: the skill's description (first sentence of its `SKILL.md` frontmatter) or the agent's, the phase with its `about` line, and the model id and effort the next step really runs on; a declared phase also says what uses it (rows, prompt rules). A row offers Later, Keep or Change; a declared phase offers Later or Keep. Change asks the model (opus, sonnet, haiku, each shown with the tier it heads; fable is not offered), then the effort among those the phases on that model use (shipped table: opus medium, high, xhigh or max; sonnet low, medium, high or xhigh; haiku has one level, so no question), then Everywhere or This project only. Rows stay phase names, so the pair maps to an existing phase: the row's current phase wins a tie and the same phase counts as Keep; a pair no phase offers needs a new phase added by hand in routing.json. Everywhere moves the row and records the shipped phase under `changed`; This project only stores an exception under `projects`, keyed by the origin remote reduced to `host/path` (no credentials, no local paths; a remote that cannot be read that way offers no project choice). Keep lands under `confirmed`; Later, a dismissed dialog or a free-text answer asks again next session. After a skill row changes, a toast names the model and effort that skill now runs on, plus a hint when the main loop holds back a downgrade: `/route switch on` when the switch is off, the cap hold (`held: downgrade skipped: cold read tokens over `) when the cold read is over `downgradeMaxTokens`. One dialog at a time, never in a headless (`-p`) run, never inside a sub-agent. +- Ask before Fable: inert by default, since no shipped tier holds fable. When a machine override puts fable at the head of `best`, before a route lifts the main loop, or sends a rowed agent, onto Fable from another model, the mod asks once per span. The question names the origin (a skill, typed or loaded by the model, an agent, the `route` tool or `/route`), the phase with its `about` line, and the model and effort the step would run on. `Fable` runs it; `Opus instead (big tier)` runs the span through the `big` tier at the phase's own effort, offered only while Opus is up so the label stays true; `Stop asking this session` pauses the question until `/clear`. A best-tier skill the model loads counts as a skill row, and an agent type gets one answer per session. Nothing is asked in a headless (`-p`) run or inside a sub-agent, a dismissed dialog runs Fable, and no answer is written (`confirmed` included). No question comes when the decision would not land on Fable (`mainUpgrade` off, a cold-read cap, the context window, Fable marked down); when such a Fable hold or cap lapses later, main upgrades without asking, as the breaker already does. `askTier` in routing.json (`best`, or `false` to turn it off) is set by `/route ask-tier on|off`, and the machine config wins. While `best` is not headed by fable, `/route ask-tier on` answers `ask-tier on (inert: best is not headed by fable)` and `/route show` prints `ask-tier: inert`. - Only a first-use dialog answer, `/route ask on|off`, `/route ask-tier on|off` or `/route forget` writes `routing.json`, never the model. Writes are serialized, capped at 64 KiB, and refused when the file is missing (it is never created). Each write leaves the config repo dirty; a toast reminds you to commit it from there. The one other write: `/model `, the bare `/model` dialog or a `/model` picker pick → This project writes the full id as `model` into the session root's `.claude/settings.local.json` (created if absent, keep it gitignored; refused when `.claude` or the file is a link, or the file is over 64 KiB or not a JSON object). Remove its `model` key to undo. - The spinner suffix and the status line under the prompt show the route in force; the status line adds ` · switch off` when the downgrade switch is off. -Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`, `askTier`), then the optional per-machine `~/.claude/model-router.json`, which wins. A `.claude/model-router.json` inside a project is never read. Machine keys: `models` (alias → full id), `windows` (context window per full id), `tiers` (ordered alias lists per tier: `best` fable>opus>sonnet, `big` opus>fable>sonnet, `work` sonnet>opus, `cheap` haiku>sonnet; the first alias not down is used), `fallback` (the rank order of the aliases, best first, used by the breaker), `cooldownMinutes` (how long a model stays marked down after an availability error, 15 by default, doubling per episode up to 300), `mainUpgrade` (default `true`: the main loop may move up to a phase's tier), `upgradeMaxTokens` (default 200000: the largest cold read a main-loop upgrade may cost), `downgradeMaxTokens` (default 120000: the same cap for a downgrade; the cold read is the context minus what the target model's prompt cache already holds, taken from main's last step on that model within the prompt-cache TTL, forgotten by `/clear` and `/route reload`. The TTL follows the engine's `cache_ttl` (5 or 60 minutes) carried by main's model-switch events, is 60 minutes until the first one and survives `/clear`. The context also counts the prompt just submitted, which the engine's usage may not include yet: code points / 3 of its text, its context entries and a typed skill's body, summed and added at the turn's first main step unless usage already grew by half of it. A `document` attachment makes the size unknown, and an unknown context size blocks the switch; the step, `/route show`, the first-use dialog and the toast read the same adjusted size), `phases`, `agents`, `skills`, `prompt` (rules), `mainModelSwitch` (default `true`: the main loop may move down to a cheaper model; a value that is not a boolean turns it off and says so), `classify` (default `true`; `false` stops the prompt classifier on that machine), `probe` (default `true`: the model main runs on, moved to or kept, is tried once, 8 seconds at most, before main is sent to it; `false` skips the probe on that machine; a non-boolean value is ignored and said; `/route show` prints `probe:`), `verbose` (default `false`; `true` logs transitions only, a non-boolean value falls back to `false`), `spinner` (default `true`), `enabled` (default `true`; `false` turns the mod off on that machine), `ask` (overrides routing.json's `ask` on that machine), `askTier` (overrides routing.json's `askTier` on that machine; `best` or `false`, any other value reads `best` and is said once). A `null` value in `agents` or `skills` drops a row. Edit phases and rows by hand in routing.json (a phase's `about`, 120 characters at most, is read from there only and shown in the dialog; a model and effort pair no phase offers needs a new phase there); without it the mod runs the code's default phases, with no rows and no dialog. `/route reload` re-reads both files. +Config layers: `mods/model-router/routing.json` (tracked: phases with their tier, effort and `about` line, rows, decisions, `ask`, `askTier`), then the optional per-machine `~/.claude/model-router.json`, which wins. A `.claude/model-router.json` inside a project is never read. Machine keys: `models` (alias → full id), `windows` (context window per full id), `tiers` (ordered alias lists per tier: `best` opus>sonnet, `big` opus>sonnet, `work` sonnet>opus, `cheap` haiku>sonnet; the first alias not down is used), `fallback` (the rank order of the aliases, best first, used by the breaker; shipped fable>opus>sonnet>haiku, so a hand pick of fable ranks above opus though no shipped tier names it), `cooldownMinutes` (how long a model stays marked down after an availability error, 15 by default, doubling per episode up to 300), `mainUpgrade` (default `true`: the main loop may move up to a phase's tier), `upgradeMaxTokens` (default 200000: the largest cold read a main-loop upgrade may cost), `downgradeMaxTokens` (default 120000: the same cap for a downgrade; the cold read is the context minus what the target model's prompt cache already holds, taken from main's last step on that model within the prompt-cache TTL, forgotten by `/clear` and `/route reload`. The TTL follows the engine's `cache_ttl` (5 or 60 minutes) carried by main's model-switch events, is 60 minutes until the first one and survives `/clear`. The context also counts the prompt just submitted, which the engine's usage may not include yet: code points / 3 of its text, its context entries and a typed skill's body, summed and added at the turn's first main step unless usage already grew by half of it. A `document` attachment makes the size unknown, and an unknown context size blocks the switch; the step, `/route show`, the first-use dialog and the toast read the same adjusted size), `phases`, `agents`, `skills`, `prompt` (rules), `mainModelSwitch` (default `true`: the main loop may move down to a cheaper model; a value that is not a boolean turns it off and says so), `classify` (default `true`; `false` stops the prompt classifier on that machine), `probe` (default `true`: the model main runs on, moved to or kept, is tried once, 8 seconds at most, before main is sent to it; `false` skips the probe on that machine; a non-boolean value is ignored and said; `/route show` prints `probe:`), `verbose` (default `false`; `true` logs transitions only, a non-boolean value falls back to `false`), `spinner` (default `true`), `enabled` (default `true`; `false` turns the mod off on that machine), `ask` (overrides routing.json's `ask` on that machine), `askTier` (overrides routing.json's `askTier` on that machine; `best` or `false`, any other value reads `best` and is said once). A `null` value in `agents` or `skills` drops a row. Edit phases and rows by hand in routing.json (a phase's `about`, 120 characters at most, is read from there only and shown in the dialog; a model and effort pair no phase offers needs a new phase there); without it the mod runs the code's default phases, with no rows and no dialog. `/route reload` re-reads both files. Limits: a main-loop switch re-reads cold the part of the context the target model's cache does not hold; a switch whose cold read is over its cap (`upgradeMaxTokens` up, `downgradeMaxTokens` down) is skipped (a `/model` hand pick is exempt) and main keeps its model, and a downgrade also needs `mainModelSwitch`. The prompt estimate is conservative (3 code points per token), so a long pasted prompt can hold back a switch that would have fit. The `/config` Model row still writes user `settings.json` with no scope question; a hand pick is dropped at `/clear`; a scope dialog never answered has no timeout. The hooks send full model ids, so the `models` table has to follow new model versions. A probe costs one small completion per model main runs on, the session's own model included, repeated only after that model is marked down, and holds that step up to 8 seconds when the model does not answer. diff --git a/USAGE.md b/USAGE.md index e255600..12f01b5 100644 --- a/USAGE.md +++ b/USAGE.md @@ -200,7 +200,7 @@ l'outil `mcp__model-router__route` (`lib/effort-shift.md`). Les skills externes vendorés (pile design, superpowers, agent-skills, skills scroll MengTo, 21st) ont aussi leur ligne. -Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par une ligne de skill, l'outil `route`, un `/route` tapé ou un choix à la main (`/model`, sélecteur). Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Opus pour Fable), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (fable, opus, sonnet, haiku, chacun avec son tier), puis le niveau parmi ceux des phases de ce modèle (fable : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; opus et haiku n'en ont qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. +Taper un skill qui a une ligne route la boucle principale dessus. Une ligne du tier best (plan, reflect, orchestrate, escalate ; `audit` est une ligne d'agent, jamais tapée) tient d'un tour à l'autre pendant tout le run, jusqu'à `/route clear`, `/route off`, un `/model` tapé ou choisi dans le sélecteur, ou un skill d'un autre tier tapé. Un `/model ` tapé, ou un choix dans le sélecteur `/model`, avec un modèle de la table demande sa portée (Échap ne change rien). Le changement du sélecteur est d'abord retenu (le moteur affiche qu'un hook l'a bloqué), puis la question vient ; un choix fait pendant qu'un autre dialogue est ouvert est refusé (`answer the open dialog first`) : This project écrit l'id complet dans `model` du `.claude/settings.local.json` du projet (créé s'il manque, à garder dans le `.gitignore`) et pose une route de modèle tenue ; This conversation pose la route seule, sans rien écrire ; Everywhere lance le `/model` natif (`settings.json` utilisateur, tous les projets). Default dans le sélecteur, sans argument, avec un nom inconnu, en headless (`-p`) ou mod coupé, le `/model` natif passe sans question. Un modèle choisi dans ce dialogue change toujours : ni plafond de relecture à froid, ni `mainUpgrade` ni `mainModelSwitch`. S'il est en panne, la boucle principale reste où elle est jusqu'à son retour. Un changement natif (ligne Model de `/config` comprise) ou `/clear` l'abandonne ; un `/route model=` tapé garde les plafonds. La ligne Model de `/config` écrit toujours le `settings.json` utilisateur, et un dialogue jamais répondu n'a pas de délai. Pour relancer un tour bloqué : `ultrathink` dans le prompt (plancher d'effort du tour) ou `/route effort=max` (tient jusqu'à `/route clear`). Le `/effort` intégré n'a pas d'effet dans un run : les lignes et les routes passent devant. Les règles de mots-clés du prompt (`plan`, `design`, `architecture`… prennent l'effort de plan ; `pourquoi`, `review`, `audit`… celui de reflect), `ultrathink` et un lancement d'agent par la boucle principale (route `orchestrate` dérivée, tenue jusqu'à la fin de ses agents en arrière-plan) ne fixent que le niveau d'effort du tour, jamais le modèle : ils ne font jamais monter la boucle principale au-dessus du modèle de la session, et un run best tenu garde son modèle. Fable n'arrive sur la boucle principale que par un choix à la main (`/model`, sélecteur), un `/route model=fable` tapé ou une config machine qui le place dans un tier : aucun tier livré ne le contient. Un prompt tapé sans règle, skill ni route en cours passe par un classifieur (un appel au petit modèle, 3 secondes au plus) : le tour prend la route de la phase devinée : son niveau d'effort, et son modèle, jamais au-dessus de celui de la session. Une devinette `coding` ou `bookkeeping` fait descendre la boucle principale vers un modèle moins cher quand `mainModelSwitch` est actif (par défaut) et que la relecture à froid tient sous `downgradeMaxTokens` (120000 tokens par défaut). Cette relecture compte aussi le prompt qui vient d'être envoyé (un token pour 3 caractères), et un document joint bloque la descente pour cette étape. Le cache compte comme chaud pendant le TTL du moteur (`cache_ttl`, 5 ou 60 minutes), 60 minutes par défaut. `/route classify off` ou `"classify": false` dans la config machine le coupe, et un `/effort` tapé entre deux tours annule la devinette pour ce tour seulement. Avant d'envoyer la boucle principale sur un modèle, celui vers lequel elle se déplace comme celui qu'elle garde (le modèle de la session compris), le mod l'essaie une fois (un appel minimal, 8 secondes au plus) : sans réponse, ce modèle est marqué en panne (raison `probe`) et la décision est reprise une fois ; `"probe": false` dans la config machine coupe cet essai, et `/route show` affiche `probe:`. Quand un modèle inférieur remplace la tête de son tier en panne (Sonnet pour Opus sur une phase best ; Opus pour Fable si une config machine met fable en tête de best), le niveau propre de la phase monte d'un cran (reflect xhigh, plan max, orchestrate high) ; un niveau demandé explicitement ou un plancher ne bouge jamais. Les sous-agents reçoivent le modèle de leur ligne au lancement (dans leur tier, jamais en dessous de leur frontmatter) et son niveau à chaque étape ; un `model` ou `effort` explicite sur l'appel gagne. Explore tourne en sonnet/medium, Plan en opus/xhigh. Un agent intégré `general-purpose` lancé par la boucle principale sans `model`, pendant que celle-ci tourne sous le modèle de la session (descente, ou repli quand un modèle est en panne), part sur le modèle de la session au lieu d'hériter du modèle inférieur ; les autres types d'agents ne sont jamais épinglés ainsi. `/route show` affiche la route en cours, slot de run compris (`main: run `), et le switch avec son plafond et ce TTL (`switch: on (downgrade, cap 120000 tokens cold, ttl 60 min)`). Première utilisation : la première fois qu'un skill avec ligne est tapé, qu'un agent avec ligne est lancé ou qu'une phase est déclarée sur la boucle principale via l'outil `route`, le mod demande une fois si la route convient. La question donne le contexte : la description du skill (première phrase du frontmatter de son `SKILL.md`) ou celle de l'agent, la phase avec sa ligne `about` (champ de la phase dans `routing.json`), puis le modèle et le niveau réels de l'étape suivante ; une phase déclarée dit aussi qui l'utilise. Pour une ligne : Later, Keep ou Change ; pour une phase déclarée : Later ou Keep. Change demande le modèle (opus, sonnet, haiku, chacun avec son tier ; fable n'est pas proposé), puis le niveau parmi ceux des phases de ce modèle (opus : medium, high, xhigh ou max ; sonnet : low, medium, high ou xhigh ; haiku n'en a qu'un, la question est sautée), puis Everywhere ou This project only (exception rangée sous le remote origin du dépôt réduit à `host/path`, jamais d'identifiants). Une ligne reste un nom de phase : le couple modèle et niveau désigne une phase existante, et la même phase qu'avant vaut Keep. Un couple qu'aucune phase n'offre s'ajoute à la main comme nouvelle phase dans `routing.json`. Après un changement sur un skill, un toast donne le modèle et le niveau réels, et rappelle `/route switch on` quand le switch est coupé, ou nomme le plafond quand la relecture à froid bloque la descente. La réponse est écrite dans `routing.json` ; Later, un texte libre (Other) ou un dialogue fermé redemande à une session suivante. Un seul dialogue à la fois, jamais en headless (`-p`) ni dans un sous-agent, et le modèle n'écrit jamais ce fichier. Chaque réponse laisse le repo de config modifié : commite-le depuis ce repo. `/route pending` liste ce qui reste à confirmer, `/route ask off|on` coupe ou rallume le dialogue, `/route forget ` efface une décision (une ligne changée revient à la phase livrée ; `all` et `projects` demandent d'abord). Si une config machine met fable en tête du tier best (aucun tier livré ne le fait), avant qu'une route envoie la boucle principale, ou un agent à ligne, sur Fable depuis un autre modèle, le mod pose une question une seule fois par portée (origine, phase et sa ligne `about`, modèle et niveau) : `Fable`, `Opus instead (big tier)` (Opus à la place : le tier big, niveau de la phase inchangé, le label reste vrai : l'option disparaît si Opus est en panne) ou `Stop asking this session` (ne plus demander cette session : rien n'est écrit, `/clear` la réarme). Un skill chargé par le modèle compte comme une ligne de skill ; un agent n'a qu'une réponse par type et par session ; jamais en headless (`-p`) ni dans un sous-agent ; un dialogue fermé lance Fable. Pas de question quand la décision ne tomberait pas sur Fable (`mainUpgrade` coupé, plafond de relecture, fenêtre, Fable en panne) : si la panne cesse plus tard, la boucle monte sans question, comme le disjoncteur le fait déjà. La clé `askTier` de `routing.json` (`best`, ou `false` pour couper) se règle par `/route ask-tier on|off`, la config machine gagne, et `/route show` affiche `ask-tier:`. Tant que best n'est pas mené par fable, la question est inerte : `/route ask-tier on` répond `ask-tier on (inert: best is not headed by fable)` et `/route show` affiche `ask-tier: inert`. Garde d'écriture : un Edit, Write ou NotebookEdit d'un fichier de code par la boucle principale est redirigé avec « model-router: code is written inside a skill run… » tant qu'aucun skill n'a tourné sur la boucle principale dans la session (tapé ou chargé par le modèle ; un skill refusé ou inconnu ne compte pas), qu'aucune phase n'a été déclarée ce tour, et qu'aucun `/route` tapé ne tient. Chemins libres : `.md`, `.txt`, le `.claude/` du projet sauf `worktrees/`, et `docs/`. Les sous-agents écrivent librement. Si la vérification du garde échoue elle-même (exception ou délai dépassé), l'écriture est retenue au lieu de passer, avec « model-router: the write guard failed (), so this write is held… », journalisé une fois par session ; les sous-agents, un skill en cours, une phase déclarée ou un `/route` tapé, et les fichiers `.md` / `.txt` passent toujours, et une erreur levée par l'outil lui-même est transmise telle quelle. `/route clear`, `/route off` et `/clear` réarment le garde ; `/route off` le coupe aussi, et `"enabled": false` dans `~/.claude/model-router.json` coupe le routeur et le garde. Un choix à la main avec `/model` ne l'ouvre pas, et un rechargement de `register.ts` le remet à zéro. From 67f27e65ae9b97a3ce78f85c8832d530d8d5f116 Mon Sep 17 00:00:00 2001 From: bchanot Date: Mon, 16 Nov 2026 23:18:48 +0100 Subject: [PATCH 3/3] chore(memory): BDR-150 Fable advisor-only routing --- .claude/memory/decisions.md | 11 + .claude/memory/journal.md | 1 + .claude/memory/learnings.md | 1 + .claude/tasks/TODO.md | 1 + .../2026-11-16-router-no-fable-1100.md | 41 +++ .../plans/2026-11-16-router-no-fable-1100.md | 280 ++++++++++++++++++ 6 files changed, 335 insertions(+) create mode 100644 .claude/tasks/contracts/2026-11-16-router-no-fable-1100.md create mode 100644 .claude/tasks/plans/2026-11-16-router-no-fable-1100.md diff --git a/.claude/memory/decisions.md b/.claude/memory/decisions.md index 6ceb400..077f4b6 100644 --- a/.claude/memory/decisions.md +++ b/.claude/memory/decisions.md @@ -1386,6 +1386,7 @@ Branch feature/user-writing-web-rules, UNMERGED (human gate). - **Amendment (2026-10-23, feat C 786ee13 + docs d2d590f)**: keyword-lift gap CLOSED: prompt rules (keywords, `ultrathink`, user rules) + derived `orchestrate` on main Agent dispatch (user pick 2026-10-23) write effort-only routes; model axis falls through to held run or stays on cur. Amends [[BDR-115]] amendment 2026-10-13 clause "ultrathink floor model beats guess": mid-turn ultrathink after classifier demotion keeps guessed model that turn (floor raises effort only). Accepted edges: haiku session → keywords no-op; session model held → keyword turn = plain-turn fallback (sonnet), not fable; no stand-in notch on keyword/dispatch turns; dispatch after demotion orchestrates on demoted model. Rejected: cap in `wantedModel` (r1) → shadowed held run slot + fail-open on `sessionModel` '' after /reload-plugins. Contract `.claude/tasks/contracts/2026-10-23-router-keyword-cap-0019.md`, plan r2.1 `.claude/tasks/plans/2026-10-23-router-keyword-cap-0019.md`. Links [[LRN-226]], [[EVAL-048]]. - **Amendment (2026-10-25, bugfix 8e93507)**: accepted edge "haiku session → keywords no-op" REVERSED (user pick: Haiku 5.x like any model). No-effort rule now Haiku 4.x only (`NO_EFFORT = 'claude-haiku-4'`); on Haiku 5.x keyword rules, `ultrathink`, sticky effort and derived orchestrate apply, unrouted step passes engine effort. Links [[BLK-035]], [[LRN-230]]. - **Status (2026-11-16)**: accepted, amended by BDR-136: ceiling model-agnostic, main loop writes no code outside a skill run on any model, held by router write guard (fail-closed since 859e504); Fable-only /hotfix-scope ceiling gone (0bf4620) +- **Status (2026-11-16)**: accepted, amended by BDR-150: no Fable via rows, opus heads best and big; session opus, Fable is the advisor ## BDR-124 — Foreign code keeps its own style; limits strict in our code only [accepted] (2026-10-23) - **Decision**: CLAUDE.global.md header: strict limits in our code, "Foreign code: keep its style" section wins on foreign code (granularity, layout, naming, comments, idioms; limits = guidelines; no refactor toward our norms unless asked). Origin = `lib/code-origin.sh`: `git config claude.origin` (ours|foreign, per clone, invalid → foreign) > root commit author vs `user.email` + global `claude.identity` list; undecidable (no git, shallow, no commit) → foreign, said. Session banner line `code : ours|foreign (reason)`. refactorer, /refactor, /audit-delta conformity follow it; refactorer cites CLAUDE.md limits, no copy. @@ -1490,6 +1491,7 @@ Supersedes [[BDR-030]]. - **Residual (user-accepted, F)**: Fable held or cap exceeded at the route event → no question, slot unstamped; hold lapse / compaction → next step upgrades unasked (breaker behaviour today). `/model ` while any dialog holds `asking` falls to native (pre-existing, BDR-126). - **Gates**: r1 correctness FATAL(6) robustness FATAL(6) simplicity CONCERNS(4) → r2 → confirmation CONCERNS(6) → r3; feater DONE 28 TIER tests (590 → 618); GATE 0 MET 5/5; verifier CONFORME 11/11 first pass; security PASS (1 LOW fixed: `clean(skill)`). Commits 9a24a62, docs 789fd00. - **Refs**: [[BDR-116]], [[BDR-123]], [[BLK-032]], [[LRN-231]], [[LRN-242]], [[LRN-254]]. +- **Status (2026-11-16)**: accepted, amended by BDR-150: ask-before-Fable inert unless an override heads best with fable; stored answers gate on fableHeadsBest ## BDR-136 — Phase 2 guards: native ask merge gate, bench-proven shell rules, rtk rc 3 passthrough, router write guard with a session skill latch, code-limits signal [accepted] (2026-11-02) - **Context**: BDR-125 phase 2, feature/phase2-guards, contract `.claude/tasks/contracts/2026-11-02-phase2-guards-1545.md`, bench `.claude/tasks/plans/2026-11-02-phase2-bench/`. @@ -1596,3 +1598,12 @@ Supersedes [[BDR-030]]. - **Alternatives rejected**: drop every routing line (loses the gstack counterweight + pack-off remedy); "never gstack ship" text in ship-feature description (ship retired from every pack, lib/gstack-removed.list: dead text); trigger "open a PR" (no skill opens a PR). - **Accepted**: description triggers not pinned by a test (darwin rewrite risk, MINOR); listing budget +~60 chars. - **Amends**: BDR-130 Deferred item done; BDR-125 phase 3 "Skill routing table lines → descriptions" done. + +## BDR-150 — Fable = advisor only, never auto-routed; Opus heads best and big [accepted] (2026-11-16) +- **Context**: user 2026-11-16: Fable set as advisor (`/advisor`, settings `advisorModel: fable`, bdbf1cd); "no auto-route on Fable, Opus = strongest model to auto-route; advisor called whenever a smarter agent is needed". feature/router-no-fable, contract `.claude/tasks/contracts/2026-11-16-router-no-fable-1100.md`, plan r3 after 2 challenge rounds. +- **Decision**: DEFAULT_CONFIG tiers `best` and `big` = ['opus','sonnet']; fable kept in `models` and at `fallback[0]` (capability rank: hand pick of fable ranks above opus, breaker never moves up to it). Row Change dialog (CHOICE_ALIASES) drops fable; bare /model keeps it ("fable (custom)"). Ask-before-Fable (askTier) fires only when alias heading best = fable (override); stored "instead" answers gate on fableHeadsBest; `/route ask-tier on` replies inert. "tiers.best does not lead the fallback chain" log deleted. routing.json untouched (askTier "best"): mod runs live from tree, old-code sessions would route Fable unasked on `askTier: false`. Agents floor = tier head (opus) for every tier. +- **Why**: Fable reasoning now comes via advisor tool (server tool, hooks cannot see/refuse it); routing main/agents to Fable duplicated cost (BLK-030 credits) and ceiling logic. +- **Alternatives rejected**: tiers in tracked routing.json (new layer code, breaks machine-key doctrine); per-machine `~/.claude/model-router.json` (not portable to work machine, near hard_deny mod clause); removing askTier feature (churn; kept dormant, `shortcut:` at TIER_HEAD); fable out of `fallback` (appended last → hand-picked fable ranks below haiku); routing.json `askTier: false` (live-install consent gap). +- **Residuals**: opus outage → best/big agents spawn on held opus (gates fail, verify-secure retries then escalates; was move-up to Fable); single opus outage → sonnet stands in with effort notch; fable-baseline session (native Everywhere) demoted to opus per downgrade caps, sessionPin pins general-purpose to fable; skill row answering opus+xhigh in Change lands on `plan`. Test rig: shipped tiers default, `legacyTiers: true` on 47 fable-mechanics tests. +- **Gates**: r1 3 lenses CONCERNS → r2 → re-challenge CONCERNS → r3; feater DONE 661 tests; GATE 0 MET; verifier CONFORME; security PASS (MEDIUM fixed: stored answer survives ask-tier off); commits 24b0f35, docs 42385d2. +- **Refs**: amends [[BDR-123]], [[BDR-135]]; supersedes [[LRN-224]]; [[BLK-030]], [[BDR-077]] (Fable dispatch pins: separate run). diff --git a/.claude/memory/journal.md b/.claude/memory/journal.md index 5e8e921..6c4735e 100644 --- a/.claude/memory/journal.md +++ b/.claude/memory/journal.md @@ -769,3 +769,4 @@ rules: - A6 router write guard fail-closed: .catch uses next.called (called → replay next(e); not called → hold main-loop out-of-run non-doc write with user-chosen deny); Skill latch ignores isError answers (BDR-137 shape, was one-call bypass) (859e504). BDR-136 (4) amended. 3 plan rounds: r1/r2 latches unreachable, engine-documented pattern won. gates.sh 120s timeout < make test ~135s: GATES_TIMEOUT=400. Next A7. - C7 hard_deny mod off-switch clause: entry 6 names enabled:false in ~/.claude/.json, enabledPlugins false, profile.sh disable of mod (8c21c4b); off switches only, no source paths (2026-10-25 challenge). Staged via crafted index blob so user's dirty settings.json /model change stayed out. Residuals (closed list, /route off in run, over-refusal risk) BUGS-FOUND e22893d. - C1-C3 BDR-125 gap: 11 status lines (BDR-125 summary; BDR-079/017 + LRN-155 superseded, 7 amended by BDR-134/136; amended entries still recalled with old title, only superseded/deprecated leave recall); C3 deferrals → 7 TODO lines + 3 dated drops; C6 dropped (throwaway repos, user). +- Router no-Fable (BDR-150, 24b0f35, docs 42385d2): best/big = opus>sonnet, fable ranked + hand pick only, Change dialog drops fable, askTier inert unless override heads best with fable; routing.json untouched (live install). 2 challenge rounds caught dialog labels, live-install consent gap, legacy rig masking. BDR-123/135 amended, LRN-224 superseded. Next: Fable pins → opus, advisor doctrine. diff --git a/.claude/memory/learnings.md b/.claude/memory/learnings.md index 3470d87..f222ea8 100644 --- a/.claude/memory/learnings.md +++ b/.claude/memory/learnings.md @@ -1771,6 +1771,7 @@ Rule: when editing a doctrine file under structure locks, grep the test's lock s - **Date**: 2026-10-21 - **Context**: feat A (routing policy BLK-032) moved verifier + security-auditor to new `audit` phase (best = fable>opus>sonnet). Plan r1 set frontmatter `model: fable` (census rule floor = tier head) and claimed "Fable down → falls to opus". False: `inTier` (register.ts) writes a model only if it is the head or ranks above it, else logs "tier … down, frontmatter model kept" → fable frontmatter = gates spawn on dead Fable every credit outage (BLK-030/031). Lower tiers never hit it (head sonnet/opus always has a higher alias). Caught by correctness + robustness lenses r1, not by plan author. - **Apply**: an agent on a best-tier row keeps opus frontmatter; router lifts to Fable when up. Census `tier_floor` (effort-routing.test.sh) locks 2nd alias for best. Residual: spawn path unprobed → first gate of an outage window still dies once, retry lands on floor (register.test.ts audit-row case b). Links [[BLK-030]], [[BLK-032]], [[LRN-204]]. +- **Status (2026-11-16)**: superseded by BDR-150: best and big headed by opus, agents floor on tier head for every tier (2nd-alias rule gone) ## LRN-225 — Gate on the tool's own exit-code contract, never on its prose; control through the gate's own helper on a clean/dirty pair - **Date**: 2026-10-22 diff --git a/.claude/tasks/TODO.md b/.claude/tasks/TODO.md index b9f7d38..2473742 100644 --- a/.claude/tasks/TODO.md +++ b/.claude/tasks/TODO.md @@ -144,6 +144,7 @@ Scope (user 2026-11-11) [gated]: D1-D6 + the 6 dead deny entries + MIGRATION/CHA - [ ] deferred (BDR-125 4c, re-challenge 2026-10-25): Read path triggers, Bash command triggers, memory_search tool for skills (analyze-before-plan pass 1); reopen when a /memory-feedback gate shows misses the prompt and error channels cannot reach (no triggers= field: 4a shipped without Meta, BDR-125 Am.7) - [ ] conditional (BDR-146 residual): a noisy entry on the tool channel survives the /prune-memory title + lesson rewrite (the 4-gram matcher reads body backtick spans, SKILL.md STEP 1.D limit); act when a tool-gate FEEDBACK.md lists one (gate 1 2026-11-12: 0 tool records) - [ ] deferred (BDR-125 Am.7, phase 2): commit-msg hook for the 50-word cap; revisit when overruns grow (4/78 on 2026-10-25; 17/530 ≈ 3 % on 2026-11-16 recount, the gap audit's 21/526 not reproducible) +- [ ] shortcut (register.ts TIER_HEAD, BDR-150): the ask-before-Fable dialog (askTier, BDR-135) is inert while no tier is headed by fable; remove the feature (TIER_HEAD, INSTEAD_TIER, tier ask paths and their LEGACY tests) if Fable never returns to a tier ### Known limits (accepted, no action) - model-router spawn path unprobed: 1st gate of an outage window dies once (seen live 2026-10-23, retry lands on the opus floor); tour/onboard/audit-delta no retry; onAutoSwitch with main on opus marks nothing if the engine auto-falls a gate off Fable diff --git a/.claude/tasks/contracts/2026-11-16-router-no-fable-1100.md b/.claude/tasks/contracts/2026-11-16-router-no-fable-1100.md new file mode 100644 index 0000000..7856f9c --- /dev/null +++ b/.claude/tasks/contracts/2026-11-16-router-no-fable-1100.md @@ -0,0 +1,41 @@ +# CONTRACT — router-no-fable (user 2026-11-16: Fable = advisor, never auto-routed) +- date: 2026-11-16 | flow: feat | branch: feature/router-no-fable (off develop) +- status: active + +## REQUEST (verbatim — IMMUTABLE) +Router: Fable leaves auto-routing (user 2026-11-16: Fable is now the advisor via /advisor; Opus becomes the strongest model the router routes to). In mods/model-router/hooks/register.ts DEFAULT_CONFIG: tiers.best and tiers.big become ['opus', 'sonnet']; fable stays in `models` and at the head of `fallback` (capability rank, so a hand-picked Fable session never ranks below opus); the mergeRouting "tiers.best does not lead the fallback chain" warning must not fire on these defaults. mods/model-router/routing.json: "askTier": false (the ask-before-head dialog was a Fable credit guard, BLK-030). Fable stays selectable by hand in the /model dialog (user choice). lib/tests/effort-routing.test.sh tier_floor: the best-tier "2nd alias" floor special case goes (floor = tier head for every tier). Tests in mods/model-router/hooks/register.test.ts: the shipped defaults route plan/judge/audit to opus, best and big never pick fable even with opus down, a hand-picked fable session is not treated as below opus, no "does not lead" log. + +## CLARIFICATIONS +- [gated 2026-11-16] user: Fable is the advisor (/advisor, settings advisorModel fable, bdbf1cd); "on ne doit plus autorouter sur fable, opus devient le model le plus puissant a autorouter"; Fable stays selectable by hand in the /model dialog. +- [internal 2026-11-16] plan .claude/tasks/plans/2026-11-16-router-no-fable-1100.md, section r2 wins. Explicit `model: "fable"` sub-agent pins and the advisor doctrine are separate runs (file cap). +- [gated 2026-11-16] user: Fable leaves the row Change dialog (CHOICE_ALIASES); the bare /model dialog keeps Fable, labelled "fable (custom)". +- [internal 2026-11-16, challenge r1] deviation from REQUEST: routing.json is NOT edited (askTier stays "best"). The mod runs live from this tree; old-code sessions reading `askTier: false` would route to Fable without consent. Instead tierHead asks nothing when best's head equals big's head (true on shipped tiers), so the dialog is inert whatever askTier says, and comes back if an override puts Fable at the head of best. The "does not lead" check is deleted, not reworded. +- [internal 2026-11-16, re-challenge r2] plan section r3 amends r2 (final): ask-before-Fable fires only when the alias at the head of `best` is `fable` (stored "instead" answers ignored otherwise; `/route ask-tier` replies say `inert`); targetPhase step dropped (already shipped); test buckets SHIPPED / LEGACY / REWRITTEN with test names reported; one-pass edit order (live install). + +- [gated 2026-11-16, after verify] user: keep routing.json as is (askTier stays "best", inert on shipped tiers). Security MEDIUM fixed: stored "Opus instead" answers gate on fableHeadsBest, not tierHead (survive `/route ask-tier off`), test added. + +## ACCEPTANCE CRITERIA +1. model-router suite green. + CHECK: cd /home/bchanot/Documents/claude && PATH=$HOME/.bun/bin:$PATH claude plugin test mods/model-router &1 | grep -cE '(^| )0 fail' + EXPECT: 1 + EVIDENCE: MET exit=0 marker-found :: 1 +2. effort-routing suite green. + CHECK: cd /home/bchanot/Documents/claude && PATH=$HOME/.bun/bin:$PATH make test suite=lib/tests/effort-routing.test.sh &1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +3. Default best and big tiers are opus then sonnet. + CHECK: cd /home/bchanot/Documents/claude && grep -cE "^ (best|big): \['opus', 'sonnet'\],$" mods/model-router/hooks/register.ts + EXPECT: 2 + EVIDENCE: MET exit=0 marker-found :: 2 +4. The "does not lead the fallback chain" check is gone. + CHECK: cd /home/bchanot/Documents/claude && { grep -c 'does not lead the fallback chain' mods/model-router/hooks/register.ts || true; } + EXPECT: 0 + EVIDENCE: MET exit=0 marker-found :: 0 +5. Full make test green (run gates with GATES_TIMEOUT=400: the full suite takes ~135 s). + CHECK: cd /home/bchanot/Documents/claude && PATH=$HOME/.bun/bin:$PATH make test &1 | tail -1 + EXPECT: all suites green + EVIDENCE: MET exit=0 marker-found :: all suites green +6. New tests on the SHIPPED defaults (plan r2 step 9 as amended by r3 step 6) exist; (i) plan/audit, (ii), (v) and (vi) options are red on the pre-change register.ts, (v) also red without r3 step 2; LEGACY-bucket tests keep their assertions unchanged; test names reported per bucket. `claude plugin validate --strict mods/model-router` passes; touched lines ≤ 80 columns (manual). + +## FILE SCOPE +mods/model-router/hooks/register.ts (DEFAULT_CONFIG tiers ~:298-303, mergeRouting check ~:618-621, CHOICE_ALIASES ~:226, tierHead ~:1177, nextAvailable ~:1147, wantedModel ~:1608, spawnTier ~:3247, flagCommand/askTierWord, comment ~:2802), mods/model-router/hooks/register.test.ts (rig fixture defaults and new tests), lib/tests/effort-routing.test.sh (tier_floor and its flip-test fixture ~:50-110). diff --git a/.claude/tasks/plans/2026-11-16-router-no-fable-1100.md b/.claude/tasks/plans/2026-11-16-router-no-fable-1100.md new file mode 100644 index 0000000..ac5a6b6 --- /dev/null +++ b/.claude/tasks/plans/2026-11-16-router-no-fable-1100.md @@ -0,0 +1,280 @@ +# PLAN — router-no-fable (Fable = advisor, Opus = strongest auto-route) + +## CONTEXT +- register.ts DEFAULT_CONFIG (~:290-305): models {haiku, sonnet, opus, + fable}; tiers best ['fable','opus','sonnet'], big ['opus','fable', + 'sonnet'], work ['sonnet','opus'], cheap ['haiku','sonnet']; fallback + ['fable','opus','sonnet','haiku'] (rank = index, best first). +- Tiers and fallback are machine keys: the tracked routing.json contributes + only phases, skills and agents (routingTables ~:887); the override + `~/.claude/model-router.json` is absent on this machine. So the shipped + policy lives in DEFAULT_CONFIG. +- mergeRouting (~:608-625) logs "tiers.best does not lead the fallback + chain; rank comes from the fallback list alone" when tiers.best[0] !== + fallback[0]. +- pickFallback/withEveryAlias (~:473-502): every `models` alias ends up + ranked; one missing from the chain is appended LAST with a log. So fable + must stay in `fallback`, at its head (true capability rank). +- askTier (BDR-135): tierHead = head of `best`; with best headed by opus + the dialog ("Fable" / "Opus instead" / stop, TIER_HEAD hardcoded) would + ask before every opus route. routing.json sets askTier. +- inTier (~:3857): an agent moves UP from its frontmatter alias to the + first available model of its tier only if that model is the head or ranks + above it; else frontmatter kept + "tier … down" log. With best/big = + [opus, sonnet] and opus down: sonnet ranks below opus → frontmatter + (opus) kept. Today big-tier agents with opus down move UP to fable; after + this change they stay on opus frontmatter (by design: never below the + floor; the engine's own fallback applies). Main loop with opus down: + breaker fallback goes down the chain to sonnet (unchanged mechanism). +- effort-routing.test.sh tier_floor (~:56-60): for `best` it reads the + tier's 2nd alias as the agents' frontmatter floor (LRN-224, Fable credit + outage); for other tiers the head. Its flip-test fixture (~:94-110) + carries the old fable tiers. +- Test rig (register.test.ts): synthetic routing.json from baseRouting() + (phases only, ~:87); tiers come from DEFAULT_CONFIG; the machine override + comes only from `fx.home` (HOME_FILE). 381 FABLE references; many tests + assume best is headed by fable. + +## APPROACH +1. register.ts DEFAULT_CONFIG: `best: ['opus', 'sonnet']`, `big: ['opus', + 'sonnet']`; models unchanged (fable kept); fallback unchanged + (['fable', 'opus', 'sonnet', 'haiku']). Comment on the tiers block: Fable + is ranked (hand picks, the advisor model) but never an auto-route target + (user 2026-11-16); a machine override may add it back to a tier. +2. register.ts mergeRouting warning: fire only when the head of `best` + ranks BELOW the head of another tier in the fallback chain (a tier + "better" than best: a real misconfiguration), not merely when it is not + fallback[0]. Wording: `model-router: tiers.best head ranks below + tiers. head in the fallback chain`. Use keyWord() for the + names. Defaults: best opus, big opus, work sonnet, cheap haiku → no log. +3. routing.json: `"askTier": false` (replaces "best"). The askTier code + stays (a machine override with `askTier: "best"` and fable back in best + still works); TIER_HEAD 'Fable' label hardcoded = residual (dormant). +4. effort-routing.test.sh: tier_floor drops the best-tier special case + (floor = tier head for every tier); its comment says why (best is headed + by opus since 2026-11-16, LRN-224's credit floor no longer applies). The + flip-test fixture moves to the new defaults (best ['opus','sonnet'], big + ['opus','sonnet']) and still proves the readers reject the wrong + verdicts. +5. register.test.ts: + a. Measure first: apply 1-3, run `claude plugin test mods/model-router`, + count red tests. + b. If more than 25 are red: add a rig default so existing mechanics + tests keep a 3-deep tier set: when a fixture gives no `home` and does + not set `shippedTiers: true`, newWorld writes HOME_FILE with + `{ tiers: { best: ['fable','opus','sonnet'], big: ['opus','fable', + 'sonnet'] } }` (machine override; nothing else in it). Tests that + assert the override's absence (source word, askTier machine value, + `fx.home` users) get `shippedTiers: true` or merge their `home` with + these tiers, case by case, without changing what they assert. If 25 + or fewer are red: update each red test's expectation to the new + defaults directly. + c. New tests, all on the SHIPPED defaults (`shippedTiers: true`, no + override): (i) typed plan, judge and audit rows route to opus (main + and spawn); (ii) with opus marked down, a best-tier and a big-tier + route never choose fable (main falls to sonnet via the breaker; a + big-tier rowed agent keeps its opus frontmatter, "tier … down" log); + (iii) a /model hand pick of fable, then a rate limit on fable → main + moves to opus (fable ranks above opus); (iv) boot logs no "does not + lead" / "ranks below" line; (v) the warning still fires on a machine + override whose best head ranks below big's head (e.g. best + ['sonnet'], big ['opus']). + d. Red-first: (i), (ii) and (iv) fail on the pre-change register.ts. + +## EDGE CASES +- Machine override re-adding fable to a tier: honored (validated by + acceptTier against models). +- Hand pick of fable through the /model dialog: unchanged (BARE_ALIASES and + CHOICE_ALIASES keep fable). +- Sessions already on fable (settings model fable): breaker and probe + unchanged; phases route down to opus only per existing downgrade rules. +- askTier absent in a foreign routing.json: code default "best" now means + asking before opus routes; acceptable (only this repo's routing.json ships + the mod) and noted as residual. + +## DISPOSITION +Amends BDR-123 (Fable via best-tier rows → no Fable auto-route; session +opus), BDR-135 (askTier off by config; code kept dormant), LRN-224 (2nd-alias +floor no longer applies: head = floor = opus). BDR-077 W1 Fable dispatch +pins handled by the next run (pins). Honors BDR-129-style single source: +the policy lives in DEFAULT_CONFIG, tracked. + +## FILES +mods/model-router/hooks/register.ts, mods/model-router/hooks/register.test.ts, +mods/model-router/routing.json, lib/tests/effort-routing.test.sh. + +## r2 (challenge r1: correctness CONCERNS(3), robustness CONCERNS(3), simplicity CONCERNS(2)) — SUPERSEDES APPROACH 2-5, EDGE CASES and DISPOSITION above +Landed: (a) the row Change dialog and /model labels change on shipped tiers +(fable heads no phase → dead option; opus heads best AND big → "opus +(best)", and targetPhase maps opus/xhigh to `plan`, judge unreachable) +(corr 1, rob 2, simp 2); (b) askTier is not dormant: `/route ask-tier on`, +a machine `askTier: "best"` or an absent key ask "Run it on fable?" and +"Opus instead" runs SONNET, gates included (corr 2, rob 1, simp 6); (c) the +mod runs live from this working tree: a routing.json `askTier: false` read +by OLD-code sessions on /clear or reload removes the Fable consent guard +while their old tiers still route to Fable (rob 4); (d) a rig default of +legacy tiers would test a config nobody ships and mask (a)/(b) (rob 3, +simp 3); (e) the warning reword is new scope (simp 1); (f) test (iv) is not +red-first, judge in (i) already opus (corr 3, simp 5); (g) flip fixture +must keep distinct heads (corr 8, rob 7, simp 4); (h) unranked `after` in +nextAvailable can display fable (corr 10). +User answers 2026-11-16: Fable leaves the row Change dialog +(CHOICE_ALIASES); /model keeps Fable, label stays "fable (custom)" (no +label code). + +1. register.ts DEFAULT_CONFIG: tiers best ['opus','sonnet'], big + ['opus','sonnet']; models and fallback unchanged (fable kept, fallback[0], + capability rank). Comment on the tiers block: Fable is ranked (hand + picks, advisor model) but never an auto-route target (user 2026-11-16); + a machine override may put it back in a tier. +2. register.ts mergeRouting: DELETE the "tiers.best does not lead the + fallback chain" check (log only, no consumer). No replacement warning. +3. register.ts CHOICE_ALIASES: ['opus', 'sonnet', 'haiku'] (fable out of + the row Change dialog). BARE_ALIASES unchanged (fable stays in /model). +4. register.ts targetPhase (~:2834-2841, row Change dialog: model+effort → + phase): tie-break when several phases match the picked model and effort + = the row's CURRENT phase first if it matches, else the first match as + today. So an agent row on `judge` answered "opus, xhigh" stays `judge`. +5. register.ts tierHead (~:1177-1181): return undefined (no tier ask) also + when the head of `best` equals the head of `big` (the "instead" option + would not be a different model). So on shipped tiers no ask fires + whatever askTier says (routing.json, machine override, `/route ask-tier + on`); a machine override putting fable back at the head of best brings + the consent dialog back unchanged. routing.json is NOT edited (askTier + stays "best"): old-code sessions keep their Fable consent guard until + /reload-plugins. `shortcut:` comment at TIER_HEAD: the ask-tier feature + is inert on shipped tiers (Fable credit guard, BLK-030); remove it if + Fable never returns to a tier; harvested into TODO.md by the closing + step. +6. register.ts nextAvailable (~:1147-1151): when `after` is given and not + ranked (findIndex -1), return undefined instead of walking from the + chain's head (display-only fable leak). +7. effort-routing.test.sh: delete tier_floor; field_of (~:64) uses + tier_head; drop the duplicate assertion (~:123) and make the best-tier + floor assertion (~:122) expect the fixture's best head. KEEP the + synthetic flip fixture's distinct heads (fable-headed best, opus-headed + big) so a wrong-tier read still fails. Comment: best is headed by opus + since 2026-11-16, the agents' floor is the tier head for every tier. +8. register.test.ts rig: shipped tiers stay the default (DEFAULT_CONFIG). + New fixture flag `legacyTiers: true` → newWorld merges `{ tiers: { + best: ['fable','opus','sonnet'], big: ['opus','fable','sonnet'] } }` + UNDER fx.home (`{ tiers: LEGACY, ...fx.home }`) into HOME_FILE. Measure + the red tests after steps 1-6; for each red test: + - the test is about a 3-deep chain or Fable mechanics (breaker or + stand-in with fable, ask-tier dialog, hand pick of fable, Fable [1m], + fable efforts) → add `legacyTiers: true`, assertion unchanged; + - the test is about shipped behavior (row labels, Change dialog options, + /model labels, rows routed on defaults, noHome / env-less routing) → + update the expected value to the shipped tiers. + Tests that set HOME_FILE directly mid-test (:705, :1812, :1835, :2328, + :2791, :3392, :3735, :4410) keep what they assert: if they need legacy + tiers, include them in the HOME_FILE they write. Report the count per + bucket. +9. New tests on the SHIPPED defaults (no legacyTiers), main booted on OPUS: + (i) typed plan and audit rows route to opus (red-first: plan and audit + went to fable); (ii) with opus marked down (switchTo(OPUS, SONNET, + 'auto') or the breaker), best and big routes never choose fable: main + on sonnet, a big-tier rowed agent keeps its opus frontmatter with the + "tier … down" log (assert the model only; the stand-in effort notch is + expected) (red-first); (iii) hand pick fable via the /model dialog, then + a rate limit on fable → main moves to opus; (iv) boot logs no "does not + lead" line (regression guard, not red-first); (v) askTier "best" in the + machine override on shipped tiers → no tier question, the audit gates + are not sent to sonnet (red-first); (vi) row Change dialog options are + opus/sonnet/haiku labels without fable, and an agent row on `judge` + answered opus + xhigh stays `judge` (red-first); (vii) bare /model + dialog still offers fable, labelled "fable (custom)". + +EDGE CASES (real behavior): +- Opus outage: best/big agents keep their opus frontmatter and spawn on the + held opus (the gates fail, verify-secure-loop retries and escalates); + today they moved up to Fable. Accepted residual (no engine fallback key + in settings.json; LRN-224 hazard moves from fable to opus). +- A single opus outage now makes sonnet stand in for the head of best and + big (standInEffort notches the row's effort up). +- A session whose baseline is fable (native /model Everywhere, not a hand + pick) is routed by the tiers: best phases go to opus, or to sonnet with + opus held. Accepted (Fable is not an auto-route target). +- Rollout: the working tree is the live install. Open sessions keep old + code until /reload-plugins; routing.json is untouched so they keep the + Fable consent dialog meanwhile. Tell the user to /reload-plugins after + the merge. + +DISPOSITION: amends BDR-123 (no Fable via rows; session opus), BDR-135 +(ask-tier inert on shipped tiers by rule, kept for overrides), LRN-224 +(floor = tier head for every tier). BDR-077 W1 Fable pins: next run. +FILES: register.ts, register.test.ts, lib/tests/effort-routing.test.sh +(routing.json dropped from scope). + +## r3 (re-challenge r2: correctness CONCERNS(3 MAJOR), robustness CONCERNS(1 MAJOR)) — amends r2; final +1. r2 step 4 DROPPED: targetPhase already prefers the row's current phase + (register.ts:2836-2843). Residual: on shipped tiers a SKILL row that + answers opus + xhigh in the Change dialog lands on `plan` (run-holding) + rather than `judge`; agents unaffected in effect (plan/judge/audit all + route opus xhigh). +2. r2 step 5 REPLACED: `tierHead` returns undefined unless the alias at + the head of `best` is `fable` (the dialog text is fable-specific: + TIER_HEAD, "Run it on fable?"). So the ask-before-Fable dialog fires + only when an override puts Fable at the head of best, whatever `big` + says. Stored answers: `wantedModel` (slot tierChoice ~:1608) and + `spawnTier` (tierSpawn ~:3247) ignore a stored "instead" answer while + tierHead(st) is undefined. `/route ask-tier on|off` keeps writing the + flag; when tierHead is undefined its reply appends ` (inert: best is not + headed by fable)` and `/route show`'s ask-tier word reads `inert` in that + case. `shortcut:` comment at TIER_HEAD: the ask-before-Fable dialog only + runs when an override heads best with fable (BLK-030 credit guard); + remove the feature if Fable never returns to a tier. +3. register.ts doc comment example at ~:2802 ("fable (best)") updated to a + shipped label ("opus (best)"). +4. Edit order: apply r2 steps 1, 2, 3, 6 and r3 step 2 in ONE pass on + register.ts before running anything (the tree is the live install: a + session started mid-edit must never see opus-headed best with the old + ask armed). +5. Test buckets (replaces r2 step 8's rule), for each red test after the + code change; report test NAMES per bucket: + a. SHIPPED (default): update the expected value to the shipped tiers. + Wins unless the assertion cannot hold on shipped tiers. + b. LEGACY: `legacyTiers: true`, assertion unchanged, ONLY when the + assertion needs a tier holding fable or a 3-deep chain (fable + breaker/stand-in, ask-before-Fable dialog, fable [1m] routing). + c. REWRITTEN: a test that answers the row Change dialog with + 'fable (best)' (fable efforts loop ~:3058, upgrade toasts ~:3164, + ~:3173, fableEfforts ~:4527 used at ~:4538, ~:4544): answer + 'opus (best)' on shipped tiers (same [medium, high, xhigh, max]), + keep the test's intent (residual f: null phase ignored, file + without phases). + Shared constants used by both buckets (ROUTED ~:2814, STEP1 ~:6440, + TO_JUDGE ~:31) are split per bucket (e.g. ROUTED_LEGACY) rather than + moving a whole group. TO_JUDGE ('opus (big)') users go LEGACY. + newWorld throws when `legacyTiers` is combined with `noHome`, an empty + env, `home: 'broken'` or kinds that turn the router off (the override + cannot be read there; a silent shipped run would lie). +6. New tests (replace r2 step 9 (i) and (v); others stand): + (i) typed plan, judge and audit rows route to opus on shipped tiers, + main booted on OPUS (plan and audit red-first; judge a guard). + (v) two cases on shipped tiers with the machine override's askTier + "best": (v-a) an audit-row spawn (auditVerifier edit, ~:7162) with an + "Opus instead" answer queued → no ask, the answer left unconsumed, the + spawn on OPUS; (v-b) main booted on SONNET types a best row → no ask, + main on OPUS. Prove (v) red against the change WITHOUT r3 step 2 (a + scratch copy with steps 1-3, 6 only), not only against the pre-change + file. (viii) override heading best AND big with fable: the dialog asks + (fable alias at the head of best). +7. Residuals restated: + - Rollout: live from the FIRST edit on the checked-out branch (new + sessions load the tree); open old-code sessions keep their dialog for + interactive best-tier routes only (old big = [opus, fable, sonnet] + still sends judge spawns to Fable unasked while opus is held; + headless runs too). After the merge: /reload-plugins in every open + session. + - Fable-baseline session: best phases now demote it to opus (or sonnet + with opus held) only through downgradeCall, so `mainModelSwitch` and + the 120k cold-read cap apply (past either, main stays on Fable); on a + demotion, sessionPin pins general-purpose spawns to the Fable session + model. + - Opus outage: best/big agents spawn on the held opus (frontmatter + floor), the gates fail, verify-secure-loop retries once then + escalates. Main: sonnet stands in with the effort notch. +FILES (final): mods/model-router/hooks/register.ts, +mods/model-router/hooks/register.test.ts, lib/tests/effort-routing.test.sh. +README.md, USAGE.md and CHANGELOG through the doc-sync step.