@marcomigozzi/trailhead 0.11.0 → 0.11.1

package/plugins/trailhead/hooks/lib/model-defaults-review.test.js

@@ -0,0 +1,437 @@
+#!/usr/bin/env node
+// Tests for model-defaults-review.js. Run: node model-defaults-review.test.js
+// No framework: plain asserts, mirrors the style of gh-subcommand.test.js.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// Isola ogni caso dal vero CLAUDE_CONFIG_DIR dell'utente: senza questo, una
+// review "global" potrebbe leggere davvero ~/.claude/trailhead/config.json.
+// Ripristinato in fondo al file; i casi che puntano altrove salvano e
+// ripristinano il valore corrente attorno a se stessi.
+const PRIOR_CLAUDE_CONFIG_DIR = process.env.CLAUDE_CONFIG_DIR;
+const BASE_CONFIG_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-globalcfg-'));
+process.env.CLAUDE_CONFIG_DIR = BASE_CONFIG_DIR;
+
+const {
+  loadData,
+  currentEntry,
+  stalePins,
+  applyUpdate,
+  semverLt,
+  reviewOffer,
+  reviewNotice,
+  findProjectRoot,
+  readAck,
+  writeAck,
+  check,
+  ack,
+  effectiveModels,
+  globalConfigDir,
+  globalConfigFile,
+  globalAckFile,
+  readAckFile,
+  writeAckFile,
+} = require('./model-defaults-review.js');
+
+const LIB_PATH = path.join(__dirname, 'model-defaults-review.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const data = loadData();
+const cur = currentEntry(data);
+ok('loadData reads the shipped JSON', data.schema === 1 && Array.isArray(data.history));
+ok('currentEntry is the last history entry', cur.since === data.history[data.history.length - 1].since);
+
+// --- stalePins -------------------------------------------------------------
+ok('no models -> stalePins empty', stalePins({}, data).length === 0);
+ok('pins already equal to the new defaults -> stalePins empty',
+  stalePins({ models: { plan: 'claude-opus-5-5', execute: 'claude-sonnet-5-5' } }, data).length === 0);
+
+{
+  const stale = stalePins({ models: { plan: 'claude-opus-4-8' } }, data);
+  ok('stale strong pin detected', stale.length === 1 &&
+    stale[0].key === 'models.plan' && stale[0].from === 'claude-opus-4-8' && stale[0].to === 'claude-opus-5-5');
+}
+
+{
+  const stale = stalePins({ models: { execute: 'claude-sonnet-5' } }, data);
+  ok('stale standard pin detected', stale.length === 1 &&
+    stale[0].key === 'models.execute' && stale[0].from === 'claude-sonnet-5' && stale[0].to === 'claude-sonnet-5-5');
+}
+
+{
+  const stale = stalePins({ models: { plan: 'claude-opus-5' } }, data);
+  ok('a superseded id (not a former plain default) is flagged too', stale.length === 1 &&
+    stale[0].key === 'models.plan' && stale[0].from === 'claude-opus-5' && stale[0].to === 'claude-opus-5-5');
+}
+
+{
+  const stale = stalePins({ models: { plan: 'claude-fable-5', review: 'inherit session' } }, data);
+  ok('unknown ids and "inherit session" are never flagged', stale.length === 0);
+}
+
+{
+  const stale = stalePins({ models: { codex: { plan: 'gpt-5.6-sol' } } }, data);
+  ok('codex pins already on current ids are not stale', stale.length === 0);
+}
+
+{
+  // Fixture sintetico: un tier codex il cui default e' cambiato, per esercitare
+  // il ramo {model, effort} che il dataset reale (codex invariato) non copre.
+  const synthetic = {
+    schema: 1,
+    history: [
+      { since: '0.1.0', claude: { strong: 'a', standard: 'b', fast: 'c' }, codex: { strong: 'old-strong', standard: 's', fast: 'f' } },
+      { since: '0.2.0', claude: { strong: 'a', standard: 'b', fast: 'c' }, codex: { strong: 'new-strong', standard: 's', fast: 'f' } },
+    ],
+  };
+  const stale = stalePins({ models: { codex: { plan: { model: 'old-strong', effort: 'high' } } } }, synthetic);
+  ok('a stale codex {model, effort} pin is detected on the model field', stale.length === 1 &&
+    stale[0].key === 'models.codex.plan' && stale[0].from === 'old-strong' && stale[0].to === 'new-strong');
+}
+
+// --- applyUpdate -------------------------------------------------------------
+{
+  const config = { other: 1, models: { plan: 'claude-opus-4-8', codex: { plan: { model: 'gpt-old', effort: 'high' } } } };
+  const stale = [
+    { key: 'models.plan', from: 'claude-opus-4-8', to: 'claude-opus-5-5' },
+    { key: 'models.codex.plan', from: 'gpt-old', to: 'gpt-new' },
+  ];
+  const next = applyUpdate(config, stale);
+  ok('applyUpdate replaces a claude string pin', next.models.plan === 'claude-opus-5-5');
+  ok('applyUpdate replaces only model in a codex {model, effort} pin, keeping effort',
+    next.models.codex.plan.model === 'gpt-new' && next.models.codex.plan.effort === 'high');
+  ok('applyUpdate does not mutate the input config',
+    config.models.plan === 'claude-opus-4-8' && config.models.codex.plan.model === 'gpt-old');
+}
+
+// --- reviewOffer / reviewNotice ----------------------------------------------
+ok('reviewOffer: ack equal to current since -> null',
+  reviewOffer({ config: { models: { plan: 'claude-opus-4-8' } }, data, ack: cur.since }) === null);
+ok('reviewOffer: older ack -> offered',
+  reviewOffer({ config: { models: { plan: 'claude-opus-4-8' } }, data, ack: '0.10.0' }) !== null);
+ok('reviewOffer: no ack, no stale pins -> null',
+  reviewOffer({ config: {}, data, ack: null }) === null);
+
+{
+  const offer = reviewOffer({ config: { models: { plan: 'claude-opus-4-8' } }, data, ack: null });
+  ok('reviewOffer notice mentions the since version', offer.notice.includes(cur.since));
+  ok('reviewOffer notice lists the stale key with -> arrow', offer.notice.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+  ok('reviewNotice never contains an em-dash', !reviewNotice(offer.stale, cur.since).includes('—'));
+  ok('reviewNotice no longer claims the offer will not reappear once acknowledged',
+    !reviewNotice(offer.stale, cur.since).includes('This offer will not reappear once acknowledged.'));
+  ok('reviewNotice says the offer reappears until acknowledged',
+    reviewNotice(offer.stale, cur.since).includes('reappears') || reviewNotice(offer.stale, cur.since).toLowerCase().includes('until'));
+}
+
+// --- fs round trip: check() is read-only --------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-'));
+  fs.mkdirSync(path.join(tmp, '.trailhead'));
+  fs.writeFileSync(path.join(tmp, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  ok('findProjectRoot finds the nearest .trailhead/config.json', findProjectRoot(tmp) === tmp);
+  ok('findProjectRoot walking from a subdir still finds it', (() => {
+    const sub = path.join(tmp, 'a', 'b');
+    fs.mkdirSync(sub, { recursive: true });
+    return findProjectRoot(sub) === tmp;
+  })());
+  ok('findProjectRoot returns null with no project above', findProjectRoot(fs.mkdtempSync(path.join(os.tmpdir(), 'th-noproj-'))) === null);
+
+  ok('readAck is null before any ack is written', readAck(tmp) === null);
+
+  const first = check(tmp);
+  ok('check() returns a notice on first run', typeof first === 'string' && first.length > 0);
+  ok('check() is read-only: writes no ack file', readAck(tmp) === null);
+  ok('check() is read-only: writes no ack file on disk either', !fs.existsSync(path.join(tmp, '.trailhead', 'model-defaults-ack')));
+
+  const second = check(tmp);
+  ok('check() returns the same notice on a second run (still not acknowledged)', second === first);
+
+  ok('the notice carries a ready-to-run ack instruction naming this lib and the project root',
+    first.includes(`node "${LIB_PATH}" ack "${tmp}"`));
+}
+
+// --- ack(cwd) ------------------------------------------------------------------
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-ack-'));
+  fs.mkdirSync(path.join(tmp, '.trailhead'));
+  fs.writeFileSync(path.join(tmp, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  ok('check() returns a notice before ack()', typeof check(tmp) === 'string');
+
+  const result = ack(tmp);
+  ok('ack() returns true when it finds a project root', result === true);
+  ok('ack() writes the current since as the ack', readAck(tmp) === cur.since);
+  ok('check() returns null after ack()', check(tmp) === null);
+}
+
+{
+  const noProj = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-ack-noproj-'));
+  ok('ack() returns false with no project above cwd', ack(noProj) === false);
+  ok('ack() never throws and writes nothing with no project above cwd',
+    !fs.existsSync(path.join(noProj, '.trailhead')));
+}
+
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-nopins-'));
+  fs.mkdirSync(path.join(tmp, '.trailhead'));
+  fs.writeFileSync(path.join(tmp, '.trailhead', 'config.json'), JSON.stringify({}));
+  const res = check(tmp);
+  ok('check() with no pins returns null', res === null);
+  ok('check() with no pins writes no ack file', readAck(tmp) === null);
+}
+
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-cli-'));
+  fs.mkdirSync(path.join(tmp, '.trailhead'));
+  fs.writeFileSync(path.join(tmp, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const out = execFileSync('node', [LIB_PATH, 'check', tmp], { encoding: 'utf8' });
+  ok('CLI check prints the notice to stdout', out.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+  ok('CLI check writes no ack file', !fs.existsSync(path.join(tmp, '.trailhead', 'model-defaults-ack')));
+
+  const ackOut = execFileSync('node', [LIB_PATH, 'ack', tmp], { encoding: 'utf8' });
+  ok('CLI ack prints nothing', ackOut === '');
+  ok('CLI ack writes the ack file', readAck(tmp) === cur.since);
+
+  const outAfterAck = execFileSync('node', [LIB_PATH, 'check', tmp], { encoding: 'utf8' });
+  ok('CLI check prints nothing after CLI ack', outAfterAck === '');
+}
+
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-cli-unknown-'));
+  let status = null;
+  try {
+    execFileSync('node', [LIB_PATH, 'bogus', tmp], { encoding: 'utf8' });
+    status = 0;
+  } catch (e) {
+    status = e.status;
+  }
+  ok('CLI with an unknown subcommand still exits 0', status === 0);
+}
+
+// --- shipped data invariants ---------------------------------------------
+{
+  const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', '..', 'package.json'), 'utf8'));
+  ok('shipped data: schema is 1', data.schema === 1);
+  let ascending = true;
+  for (let i = 1; i < data.history.length; i++) {
+    if (!semverLt(data.history[i - 1].since, data.history[i].since)) ascending = false;
+  }
+  ok('shipped data: history is ascending by since', ascending);
+  const complete = data.history.every((e) => ['claude', 'codex'].every((h) =>
+    ['strong', 'standard', 'fast'].every((t) => typeof e[h][t] === 'string' && e[h][t].length > 0)));
+  ok('shipped data: every entry is a complete snapshot (3 tiers x 2 hosts)', complete);
+  ok('shipped data: last since <= package.json version',
+    cur.since === pkg.version || semverLt(cur.since, pkg.version));
+  const plugin = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '.claude-plugin', 'plugin.json'), 'utf8'));
+  ok('shipped data: last since <= plugin.json version',
+    cur.since === plugin.version || semverLt(cur.since, plugin.version));
+}
+
+{
+  const refDoc = fs.readFileSync(
+    path.resolve(__dirname, '..', '..', 'skills', '_shared', 'configuration-reference.md'), 'utf8');
+  ok('drift guard: current claude strong id appears in the Tier-class -> id section',
+    refDoc.includes(cur.claude.strong));
+  ok('drift guard: current claude standard id appears in the Tier-class -> id section',
+    refDoc.includes(cur.claude.standard));
+}
+
+// --- effectiveModels (pure merge, no mutation) --------------------------------
+{
+  const globalModels = { plan: 'g-plan', execute: 'g-exec', codex: { plan: { model: 'g-gpt', effort: 'high' } } };
+  const projectModels = { plan: 'p-plan', codex: { plan: { model: 'p-gpt' } } };
+  const layers = [
+    { layer: 'global', file: '/g/trailhead/config.json', config: { models: globalModels } },
+    { layer: 'project', file: '/p/.trailhead/config.json', config: { models: projectModels } },
+  ];
+  const { config, sources } = effectiveModels(layers);
+  ok('effectiveModels: a project key wins over the global one', config.models.plan === 'p-plan');
+  ok('effectiveModels: a global-only key survives when the project does not set it', config.models.execute === 'g-exec');
+  ok('effectiveModels: a project codex key replaces the global one atomically (no inherited effort)',
+    config.models.codex.plan.model === 'p-gpt' && config.models.codex.plan.effort === undefined);
+  ok('effectiveModels: sources tags models.plan as the project layer',
+    sources['models.plan'].layer === 'project' && sources['models.plan'].file === '/p/.trailhead/config.json');
+  ok('effectiveModels: sources tags models.execute as the global layer',
+    sources['models.execute'].layer === 'global' && sources['models.execute'].file === '/g/trailhead/config.json');
+  ok('effectiveModels: sources tags models.codex.plan as the project layer',
+    sources['models.codex.plan'].layer === 'project' && sources['models.codex.plan'].file === '/p/.trailhead/config.json');
+  ok('effectiveModels does not mutate the input layer configs',
+    globalModels.plan === 'g-plan' && projectModels.codex.plan.model === 'p-gpt' && !('effort' in projectModels.codex.plan));
+}
+
+{
+  const layers = [
+    { layer: 'global', file: '/g/config.json', config: { models: { plan: 'claude-opus-4-8' } } },
+    { layer: 'project', file: '/p/config.json', config: { models: { plan: null } } },
+  ];
+  const { config, sources } = effectiveModels(layers);
+  ok('effectiveModels: a project null value wins over global by own-key presence, not truthiness', config.models.plan === null);
+  ok('effectiveModels: source for plan is the project even though its value is null', sources['models.plan'].layer === 'project');
+}
+
+{
+  const layers = [
+    { layer: 'global', file: '/g/config.json', config: { models: { plan: 'claude-opus-4-8' } } },
+    { layer: 'project', file: '/p/config.json', config: { models: { plan: '' } } },
+  ];
+  const { config } = effectiveModels(layers);
+  ok('effectiveModels: a project empty-string value wins over global by own-key presence', config.models.plan === '');
+}
+
+{
+  const layers = [
+    { layer: 'global', file: '/g/config.json', config: { models: { codex: { plan: { model: 'g-gpt' } } } } },
+    { layer: 'project', file: '/p/config.json', config: { models: { codex: 'not-an-object' } } },
+  ];
+  const { config, sources } = effectiveModels(layers);
+  ok('effectiveModels: a malformed project codex wins wholesale, yielding no codex pins', config.models.codex === 'not-an-object');
+  ok('effectiveModels: a malformed project codex clears prior codex sources', !sources['models.codex.plan']);
+}
+
+{
+  const layers = [{ layer: 'global', file: '/g/config.json', config: { models: null } }];
+  const { config } = effectiveModels(layers);
+  ok('effectiveModels: a layer whose models is not a plain object contributes nothing', Object.keys(config.models).length === 0);
+}
+
+// --- stalePins with a malformed codex value -------------------------------
+ok('stalePins: a non-object models.codex yields no codex pins (not an exception)',
+  stalePins({ models: { codex: 'oops' } }, data).length === 0);
+
+// --- check()/ack(): global config merged under the project ---------------
+{
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+  const globalDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-global-'));
+  process.env.CLAUDE_CONFIG_DIR = globalDir;
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-proj-empty-'));
+  fs.mkdirSync(path.join(projectDir, '.trailhead'));
+  fs.writeFileSync(path.join(projectDir, '.trailhead', 'config.json'), JSON.stringify({}));
+
+  const notice = check(projectDir);
+  ok('check(): a project with an empty config still flags a stale global pin',
+    typeof notice === 'string' && notice.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+  ok('check(): the stale global pin line is tagged with the global config path',
+    notice.includes(path.join(globalDir, 'trailhead', 'config.json')));
+
+  process.env.CLAUDE_CONFIG_DIR = savedEnv;
+}
+
+{
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+  const globalDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-global2-'));
+  process.env.CLAUDE_CONFIG_DIR = globalDir;
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-proj-override-'));
+  fs.mkdirSync(path.join(projectDir, '.trailhead'));
+  fs.writeFileSync(path.join(projectDir, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-5-5' } }));
+
+  ok('check(): a project pin overriding a stale global pin is not flagged', check(projectDir) === null);
+
+  process.env.CLAUDE_CONFIG_DIR = savedEnv;
+}
+
+{
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+  const globalDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-global-only-'));
+  process.env.CLAUDE_CONFIG_DIR = globalDir;
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const noProjDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-noproj2-'));
+
+  const notice = check(noProjDir);
+  ok('check(): no project above cwd but a global config exists -> a notice',
+    typeof notice === 'string' && notice.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+  ok('check(): the global-only case writes nothing', !fs.existsSync(path.join(globalDir, 'trailhead', 'model-defaults-ack')));
+
+  const ackResult = ack(noProjDir);
+  ok('ack(): the global-only case writes the global ack and returns true',
+    ackResult === true && fs.existsSync(path.join(globalDir, 'trailhead', 'model-defaults-ack')));
+
+  ok('check(): the global-only case is silenced after the global ack', check(noProjDir) === null);
+
+  process.env.CLAUDE_CONFIG_DIR = savedEnv;
+}
+
+{
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+  const globalDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-global-bad-'));
+  process.env.CLAUDE_CONFIG_DIR = globalDir;
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), '{ not valid json');
+
+  const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-proj-malformed-global-'));
+  fs.mkdirSync(path.join(projectDir, '.trailhead'));
+  fs.writeFileSync(path.join(projectDir, '.trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const notice = check(projectDir);
+  ok('check(): a malformed global config does not block the project review',
+    typeof notice === 'string' && notice.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+
+  process.env.CLAUDE_CONFIG_DIR = savedEnv;
+}
+
+{
+  const savedEnv = process.env.CLAUDE_CONFIG_DIR;
+  const globalDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-global-mixed-'));
+  process.env.CLAUDE_CONFIG_DIR = globalDir;
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const projectDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-proj-mixed-'));
+  fs.mkdirSync(path.join(projectDir, '.trailhead'));
+  fs.writeFileSync(path.join(projectDir, '.trailhead', 'config.json'), JSON.stringify({ models: { execute: 'claude-sonnet-5' } }));
+
+  const notice = check(projectDir);
+  const globalConfigPath = path.join(globalDir, 'trailhead', 'config.json');
+  const projectConfigPath = path.join(projectDir, '.trailhead', 'config.json');
+  ok('check(): mixed sources - the global stale key is tagged with the global config path',
+    notice.includes(`models.plan: claude-opus-4-8 -> claude-opus-5-5 (new default; from the global config, ${globalConfigPath})`));
+  ok('check(): mixed sources - the project stale key is tagged with the project config path',
+    notice.includes(`models.execute: claude-sonnet-5 -> claude-sonnet-5-5 (new default; from the project config, ${projectConfigPath})`));
+
+  process.env.CLAUDE_CONFIG_DIR = savedEnv;
+}
+
+// --- CLI check/ack honouring CLAUDE_CONFIG_DIR ----------------------------
+{
+  const globalDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-cli-global-'));
+  fs.mkdirSync(path.join(globalDir, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(globalDir, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const noProjDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-cli-noproj-'));
+
+  const out = execFileSync('node', [LIB_PATH, 'check', noProjDir], {
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_CONFIG_DIR: globalDir },
+  });
+  ok('CLI check with CLAUDE_CONFIG_DIR set flags a global-only stale pin',
+    out.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+
+  const ackOut = execFileSync('node', [LIB_PATH, 'ack', noProjDir], {
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_CONFIG_DIR: globalDir },
+  });
+  ok('CLI ack with CLAUDE_CONFIG_DIR set writes the global ack',
+    ackOut === '' && fs.existsSync(path.join(globalDir, 'trailhead', 'model-defaults-ack')));
+}
+
+console.log(`model-defaults-review.test.js: ${passed} assertions passed`);
+
+if (PRIOR_CLAUDE_CONFIG_DIR === undefined) {
+  delete process.env.CLAUDE_CONFIG_DIR;
+} else {
+  process.env.CLAUDE_CONFIG_DIR = PRIOR_CLAUDE_CONFIG_DIR;
+}

package/plugins/trailhead/hooks/lib/model-defaults.json

@@ -0,0 +1,12 @@
+{
+  "schema": 1,
+  "history": [
+    { "since": "0.5.1",
+      "claude": { "strong": "claude-opus-4-8", "standard": "claude-sonnet-5", "fast": "claude-haiku-4-5-20251001" },
+      "codex":  { "strong": "gpt-5.6-sol", "standard": "gpt-5.6-terra", "fast": "gpt-5.6-luna" } },
+    { "since": "0.11.0",
+      "claude": { "strong": "claude-opus-5-5", "standard": "claude-sonnet-5-5", "fast": "claude-haiku-4-5-20251001" },
+      "codex":  { "strong": "gpt-5.6-sol", "standard": "gpt-5.6-terra", "fast": "gpt-5.6-luna" },
+      "supersedes": { "claude": { "strong": ["claude-opus-5"], "standard": ["claude-sonnet-4-8"] } } }
+  ]
+}

package/plugins/trailhead/hooks/trailhead-check-update.js

@@ -105,9 +105,11 @@ function latestGitHub() {
   return '';
 }
 
-function main() {
+// Calcola la notice dell'update (solo Codex, comportamento invariato).
+// Ritorna null se non c'è nulla da segnalare.
+function updateNotice() {
   const info = detect();
-  if (!SEMVER.test(clean(info.version))) return; // versione installata sconosciuta: non azzardare
+  if (!SEMVER.test(clean(info.version))) return null; // versione installata sconosciuta: non azzardare
   const out = cacheFile(info.host); // cache per-host: Codex non eredita il verdetto di Claude
 
   // throttle: se la cache è fresca (<6h) riusa quel verdetto senza richiamare la rete
@@ -119,7 +121,7 @@ function main() {
     verdict = prev;
   } else {
     const latest = (info.channel === 'npm' || info.channel === 'codex') ? latestNpm() : latestGitHub();
-    if (!SEMVER.test(clean(latest))) return; // rete/fonte non disponibile: lascia la cache com'è
+    if (!SEMVER.test(clean(latest))) return null; // rete/fonte non disponibile: lascia la cache com'è
 
     verdict = {
       channel: info.channel,
@@ -138,18 +140,71 @@ function main() {
 
   // Codex non ha una statusline: l'hook stesso deve segnalare l'update
   // disponibile via additionalContext, su OGNI sessione (non solo quando la
-  // finestra di throttle si riapre). Su Claude (info.host è undefined) non
-  // scrive mai su stdout: comportamento invariato.
+  // finestra di throttle si riapre). Su Claude (info.host è undefined) resta
+  // sempre null: comportamento invariato.
   if (info.host === 'codex' && verdict && verdict.updateAvailable === true && SEMVER.test(clean(verdict.latest))) {
-    process.stdout.write(JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: 'SessionStart',
-        additionalContext: `Heads up: trailhead ${verdict.latest} is available (you have ${verdict.installed}). Run $trailhead update to install it.`,
-      },
-    }));
+    return `Heads up: trailhead ${verdict.latest} is available (you have ${verdict.installed}). Run $trailhead update to install it.`;
   }
+  return null;
 }
 
-// esegui in background: non blocca l'avvio della sessione.
-// L'hook stesso ritorna subito; il lavoro (rete) è dentro main() con timeout brevi.
-try { main(); } catch { /* mai far fallire SessionStart */ }
+// Notice di revisione dei pin dei modelli (#186): calcolata PRIMA e a
+// prescindere dall'update check, cosi' un early-return di quest'ultimo
+// (versione ignota, rete assente) non la fa mai cadere. Il require è dentro
+// un try: una lib mancante non deve mai rompere SessionStart. check() è di
+// sola lettura (#187): non scrive l'ack, quindi ripropone la notice finche'
+// l'agente non chiama la subcommand "ack" della stessa lib, dopo che
+// l'utente ha risposto a una delle tre scelte della notice.
+function reviewNotice(cwd) {
+  try {
+    return require('./lib/model-defaults-review.js').check(cwd) || null;
+  } catch {
+    return null;
+  }
+}
+
+// Legge il JSON di SessionStart da stdin in modo asincrono, con timeout, come
+// gli altri hook: una lettura sincrona di fd 0 si bloccherebbe per sempre su
+// un TTY o su una pipe mai chiusa. Su TTY o input assente si prosegue con {}.
+const STDIN_TIMEOUT_MS = 2000;
+function readInput(done) {
+  if (process.stdin.isTTY) return done({});
+  let data = '';
+  let finished = false;
+  const finish = () => {
+    if (finished) return;
+    finished = true;
+    clearTimeout(timer);
+    try { process.stdin.destroy(); } catch { /* ignore */ }
+    let input = {};
+    try { input = JSON.parse(data || '{}'); } catch { input = {}; }
+    done(input && typeof input === 'object' ? input : {});
+  };
+  const timer = setTimeout(finish, STDIN_TIMEOUT_MS);
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', finish);
+  process.stdin.on('error', finish);
+}
+
+function main(input) {
+  const cwd = (input && typeof input.cwd === 'string' && input.cwd) || process.cwd();
+
+  const review = reviewNotice(cwd);
+  const update = updateNotice();
+
+  const parts = [review, update].filter(Boolean);
+  if (!parts.length) return;
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: parts.join('\n\n'),
+    },
+  }));
+}
+
+// L'hook non deve MAI far fallire SessionStart: ogni errore degrada in silenzio.
+// Il lavoro (rete) è dentro main() con timeout brevi.
+try {
+  readInput((input) => { try { main(input); } catch { /* mai far fallire SessionStart */ } });
+} catch { /* mai far fallire SessionStart */ }

package/plugins/trailhead/skills/_shared/configuration-reference.md

@@ -37,6 +37,8 @@ Effective config = built-in defaults ← global `~/.claude/trailhead/config.json
 
 **Inline update check (hookless hosts).** On a host without a hook bus (the descriptor's `hookBus == 'none'`) the `trailhead-check-update.js` SessionStart hook and the statusline flag are both absent, so the engine does the check **inline at session start**, co-located with the models-collapse notice above. It is lightweight and degrades silently: read the shared cache (`$XDG_CACHE_HOME/trailhead/update-check.json`, the same file the hook writes on Claude Code) and, if it reports an update, surface a one-line notice pointing at `/trailhead:update` (the pure `updateNotice(host, cache)` helper in `bin/lib/host-descriptor.js` is the canonical wording, and returns null on a host that already notifies via the hook, so it never double-fires); if the cache is absent or stale (older than a few hours), do a minimal throttled compare of the installed `VERSION` against the latest (npm registry or the GitHub release, per install channel) and rewrite the cache **atomically** (write a temp file in the same directory as the target, then rename it over the target, exactly as the `trailhead-check-update.js` SessionStart hook does with `out + '.tmp'` then `renameSync`), so a crash mid-write cannot leave a truncated or corrupt cache. Never block or fail the session on a network or parse error. `/trailhead:update` stays the on-demand installer.
 
+**Pinned model review.** After an update that changed the tier defaults, the engine offers to review pinned `models.*` / `models.codex.*` ids that are older than their tier's new default (listed `key: old -> new`), with three choices: update (write the new ids, codex effort unchanged), keep (nothing to do, not asked again for these defaults), or open `/trailhead:config` to pick per key. The review evaluates the **effective** pins: the global `~/.claude/trailhead/config.json` merged under the project's `.trailhead/config.json`, project winning key by key (a project's own key, even `null`, `''`, or `inherit session`, always wins over the global value; `models.codex` follows the same per-key rule, so a stale pin inherited from the global config is flagged too, even for a project that pins nothing itself). Each stale line names the config file it actually came from, so the update choice edits the right one. The check (`model-defaults-review.js`'s `check(cwd)`, CLI subcommand `check`) is **read-only**: it never writes an ack by itself, so it keeps reoffering until the user actually answers. The ack (CLI subcommand `ack`, writing the acknowledged defaults version) is written only after the user picks one of the three choices, never just for the notice having been shown; it lives in the gitignored `.trailhead/model-defaults-ack` file when a project is found above `cwd`, whether the stale pin itself is project or global. With no project found above `cwd`, the review runs on the global config alone (if one exists) and its ack lives next to it, at `<config dir>/trailhead/model-defaults-ack` (config dir = `$CLAUDE_CONFIG_DIR` or `~/.claude`). The check runs both in the `trailhead-check-update.js` SessionStart hook and at skill config load (`../_shared/load-first.md`), once per session either way. Unset keys already follow the new defaults, so they are never flagged; unknown ids (custom or unrecognised) are never flagged either. The tier history lives in `hooks/lib/model-defaults.json`. Hookless hosts run the same `node <hooks>/lib/model-defaults-review.js check <dir>` / `... ack <dir>` pair inline at session start.
+
 If a value is unset, it resolves to its **Balanced**-profile default for that activity (the default profile: a project with no config still gets the Balanced tier per key, resolved to a concrete id at load time, strong → `claude-opus-5-5`, standard → `claude-sonnet-5-5`, fast → Haiku-class). To use the session model instead of the Balanced default, set the key explicitly to `inherit session`. Never hard-fail on an unknown id: warn and inherit the session model.
 
 **Everything else runs in the main session on its own model, there is no key for it:** charting, grilling, naming the destination, framing and **writing the tickets**, graduating fog, and map/decision operations. That's deliberate: it's HITL/orchestration work (you reason *with* the user), so the model that writes a ticket is the one grilling you; it can't fan out to a subagent. Practical upshot: **run a charting session (`/trailhead:new`/`:adopt`/`:ticket`) on your strong model**. The `models.*` keys above govern only the fan-out activities, not the quality of the tickets themselves. **Store a full model id** (e.g. `claude-opus-5-5`, `claude-fable-5`), never a bare family alias like `opus`; a family now spans several live versions, so an alias can't say which one. (On Claude Code the `Agent` tool takes only a family alias, so at subagent spawn the stored id is mapped to its alias, see the dispatch rule in `techniques.md`; the full id is still what gets stored, so the exact version stays on record and drives the inline-vs-subagent decision, even though the alias-only spawn cannot convey that version to the subagent.) **`models.plan` and `models.execute` are always distinct choices**: never collapse them into one shared model pick, even when the user would pick the same id for both.
@@ -52,6 +54,7 @@ If a value is unset, it resolves to its **Balanced**-profile default for that ac
 **Tier-class -> id**, resolved from the lineup actually reachable at setup time (verify, don't trust these verbatim):
 - **Claude** (`models.*`, ids only, no effort): strong = Opus-class, resolved to **`claude-opus-5-5`** by default (`claude-opus-5` stays offered in the per-key menus) · standard = Sonnet-class, resolved to **`claude-sonnet-5-5`** by default (so Balanced's `execute` runs on Sonnet 5.5; `claude-sonnet-5` stays offered in the per-key menus) · fast = Haiku-class.
 - **Codex** (`models.codex.*`, `{model, effort}`): strong = `gpt-5.6-sol` @ `high` (debug on **High** may be `xhigh`) · standard = `gpt-5.6-terra` @ `medium` · fast = `gpt-5.6-luna` @ `low`.
+- Changing a tier default must append a complete new entry to `hooks/lib/model-defaults.json` in the same commit.
 
 **Ticket language.** `ticket.language` (ISO 639-1, default `en`) sets the language trailhead **writes** in on the Issues: ticket titles and bodies, engine comments (DISCUSS/PLAN/VERIFY/OPTIONS/REPRO/DIAGNOSIS/PAUSED/resolution), the map body sections, and commit message **descriptions**. It's fully decoupled from the language the agent *converses* in (its session/global setting); setting `ticket.language` never changes how the agent talks to the user. **Untouched by it:** code and identifiers, the fixed `trailhead:*` label names, config keys/values, and the conventional-commit type prefix (`feat:`/`fix:` stay English). The skill's own source docs (SKILL.md, `references/`) are not project prose and stay English.
 
@@ -65,7 +68,7 @@ If a value is unset, it resolves to its **Balanced**-profile default for that ac
 
 **plan_review.** `off` (default) = build PLANs are not externally reviewed; `on` = review with every external AI CLI detected on the PATH; a comma list (`gemini,codex`) = only those. Needs the named CLIs installed; if none are available it's skipped, never failed. The `build` engine's Plan step runs **Cross-AI plan review** when this is on.
 
-**code_review.rounds.** Integer, default 2. The max fix-and-re-review rounds the **Code review** technique spends chasing **Critical** (blocking) findings during the `build`/`bug` Verify step. When the budget is exhausted with Critical findings still open, the technique never resolves or continues silently: it surfaces an explicit HITL checkpoint (run another 2 rounds vs proceed with the blockers recorded). Mirrors `plan_review.rounds`.
+**code_review.rounds.** Integer, default 2. The max fix-and-re-review rounds the **Code review** technique spends chasing **Critical** (blocking) findings during the `build`/`bug` Verify step. When the budget is exhausted with Critical findings still open, the technique never resolves or continues silently: it surfaces an explicit HITL checkpoint (run another 2 rounds, proceed with the blockers recorded, or run until it converges). Mirrors `plan_review.rounds`.
 
 **effort (cost-aware gating).** `standard` (default) = the full flow for the map cycle: every `build`/`bug` step runs at full cost, no triage (today's behaviour, backward-compatible). `lean` = **cost-aware**, defined **canonically here**; the `build`/`bug` engine references this section under `lean` and adds only its own timing. **`quick` is the exception: it runs the size triage and the offer below on *every* ticket, independent of `effort`** (reaching for `quick` is itself the small-piece signal; `effort` governs the map cycle, not `quick`, see `../trailhead-work/SKILL.md`). Under `lean` (and always for `quick`) the engine runs a **size triage** in the orchestrator (main session, inline, no subagent, so the triage itself costs almost nothing), classifying the change predictively from the ticket scope and a quick glance at the target files (the real diff is unknown before Execute):
 - **trivial**: a single file, a handful of lines, no new seam, no new dependency, no architectural change (a copy/CSS/doc/constant edit).

package/plugins/trailhead/skills/_shared/configuration.md

@@ -5,4 +5,4 @@ Three layers, **nearest wins**, key by key; a key unset at one layer inherits th
 - **Global**: `~/.claude/trailhead/config.json` (honour `$CLAUDE_CONFIG_DIR`): your standing defaults across every project.
 - **Defaults**: the built-in values documented in `configuration-reference.md`.
 
-Load the effective config at the start of a work session, **from the map's project root** (`.trailhead/config.json` at the superproject repo root) plus the global file, **before** any isolation workspace is set up. **Config is a property of the project/map, not the working directory**: an `isolation: worktree`/`clone` workspace **inherits** the config loaded here and must **never re-resolve it from the isolated copy's own root**. A per-ticket clone is always a clone of the **superproject** (never of a submodule alone), so its `.trailhead/config.json` is present when the project commits one and absent when it doesn't; either way re-resolving there is wrong, because the workspace must reuse the config already resolved from the original checkout, not load it afresh (an absent file would silently fall back to defaults, which is exactly how a `design: claude.ai/design` project ends up wrongly using `disk` in a clone). Config **writes** too (e.g. caching `design.project`) target the project's `.trailhead/config.json` in the original checkout, never the clone. **The main session orchestrates and holds the HITL moments** (the `build`/`bug` Discuss's "stop and ask", Verify's acceptance/UAT); **every model key runs as a subagent** (`plan`, `execute` (an *executor subagent* implementing with atomic commits on `models.execute`), `research`, `review`, `debug`, `verify`, `codebase-map`) so the whole per-activity model split applies in one session whatever model it runs on. Run Execute inline only when `models.execute` is unset or equals the session model. **On a subagent-less host** (`subagentToolkit == none`) there is nothing to fan out into: every activity runs inline. **Separately, on a host that can't honour the model keys** (`honorsModelKeys == false`, e.g. Codex, whose subagents run on its own OpenAI models) every `models.*` key collapses to the single session model even though the activities still fan out; when any `models.*` is set there the engine surfaces a **one-time** session-start notice that the split is not taking effect (the keys stay in `.trailhead/config.json` for when the project next runs on Claude Code). On Codex the per-activity split is available through a parallel `models.codex.*` namespace (OpenAI model ids), the honoured namespace there (projected into per-technique `~/.codex/agents/*.toml` and dispatched at runtime by `agent_type`), while `models.*` (Claude ids) still collapse to the single session model; the collapse notice points at `models.codex.*` and goes silent once it is set. A host without a hook bus (`hookBus == none`) also runs a lightweight inline update check at session start (no SessionStart hook, no statusline). See `configuration-reference.md`. The **keys, their values, the model/tdd/acceptance semantics, and the guided menu setup live in `configuration-reference.md`**: read it when running `/trailhead:config` or when you need a key's exact meaning. `/trailhead:config` with no args runs the guided setup; `config get` prints the merged config; `config set <key> <value>` writes one key.
+Load the effective config at the start of a work session, **from the map's project root** (`.trailhead/config.json` at the superproject repo root) plus the global file, **before** any isolation workspace is set up. **Config is a property of the project/map, not the working directory**: an `isolation: worktree`/`clone` workspace **inherits** the config loaded here and must **never re-resolve it from the isolated copy's own root**. A per-ticket clone is always a clone of the **superproject** (never of a submodule alone), so its `.trailhead/config.json` is present when the project commits one and absent when it doesn't; either way re-resolving there is wrong, because the workspace must reuse the config already resolved from the original checkout, not load it afresh (an absent file would silently fall back to defaults, which is exactly how a `design: claude.ai/design` project ends up wrongly using `disk` in a clone). Config **writes** too (e.g. caching `design.project`) target the project's `.trailhead/config.json` in the original checkout, never the clone. **The main session orchestrates and holds the HITL moments** (the `build`/`bug` Discuss's "stop and ask", Verify's acceptance/UAT); **every model key runs as a subagent** (`plan`, `execute` (an *executor subagent* implementing with atomic commits on `models.execute`), `research`, `review`, `debug`, `verify`, `codebase-map`) so the whole per-activity model split applies in one session whatever model it runs on. Run Execute inline only when `models.execute` is unset or equals the session model. **On a subagent-less host** (`subagentToolkit == none`) there is nothing to fan out into: every activity runs inline. **Separately, on a host that can't honour the model keys** (`honorsModelKeys == false`, e.g. Codex, whose subagents run on its own OpenAI models) every `models.*` key collapses to the single session model even though the activities still fan out; when any `models.*` is set there the engine surfaces a **one-time** session-start notice that the split is not taking effect (the keys stay in `.trailhead/config.json` for when the project next runs on Claude Code). On Codex the per-activity split is available through a parallel `models.codex.*` namespace (OpenAI model ids), the honoured namespace there (projected into per-technique `~/.codex/agents/*.toml` and dispatched at runtime by `agent_type`), while `models.*` (Claude ids) still collapse to the single session model; the collapse notice points at `models.codex.*` and goes silent once it is set. A host without a hook bus (`hookBus == none`) also runs a lightweight inline update check at session start (no SessionStart hook, no statusline). After an update changes the tier defaults, a pinned-model review offer surfaces too, once per session and until the user answers it (see `../_shared/load-first.md` for the check/ack sequence and `configuration-reference.md`'s Pinned model review). See `configuration-reference.md`. The **keys, their values, the model/tdd/acceptance semantics, and the guided menu setup live in `configuration-reference.md`**: read it when running `/trailhead:config` or when you need a key's exact meaning. `/trailhead:config` with no args runs the guided setup; `config get` prints the merged config; `config set <key> <value>` writes one key.

package/plugins/trailhead/skills/_shared/load-first.md

@@ -16,3 +16,5 @@ Before doing anything, read the shared core, in order:
 **Host command forms (standing render rule).** Every trailhead command you write in prose you generate at runtime, the session handoff, a capture confirmation, any next-step suggestion, and not only where a doc example already shows one, uses **this host's command forms**: `/clear` to clear context, and the `/trailhead:<verb>` family (`/trailhead:work <n>`, `/trailhead:quick <n>`, `/trailhead:map`, `/trailhead:dashboard`). These literals are this host's surface. **Never emit a command form that belongs to a different host** (one you may have read elsewhere in this repository, such as in the projection code and its tests, or earlier in the session): the forms stated in this contract are the only ones correct for the host you are running on.
 
 Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file), before any isolation workspace is set up.
+
+**Pinned model review, once per session.** After loading the effective config, run the read-only check: `node <lib> check <project root>`, where `<lib>` is the first of these two paths (relative to this `_shared/` dir) that exists: `../../hooks/lib/model-defaults-review.js` (Claude plugin, Claude npm copy, dev-symlink install), else `../trailhead/hooks/lib/model-defaults-review.js` (Codex). If neither exists, skip silently. If it prints a notice, offer it to the user without blocking the current request; only after the user answers any of its three choices, run `node <lib> ack <project root>`. Do this at most once per session: skip it if the SessionStart hook (or an earlier config load this session) already surfaced the same offer. Repeats across sessions are expected until the user answers.