@marcomigozzi/trailhead 0.10.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/hooks/trailhead-secret-read-guard.js

@@ -44,6 +44,11 @@
 // are shared with trailhead-search-guard.js via lib/shell-scan.js, so the two
 // guards can never drift into two divergent tokenizers again.
 //
+// #180 fix: `docker`/`podman` `--env-file .env` (or `--env-file=.env`) was a
+// false positive: the container RUNTIME reads that file, not the agent. Only
+// that flag's value is exempted, and only for docker/podman verbs; see
+// ENV_FILE_EXEMPT_VERBS below.
+//
 // Deliberately best-effort on the Bash leg, like the sibling guards: not a
 // full shell parser. It does not care about `cd` shape at all (that is
 // trailhead-search-guard.js's job) — it only asks "does any token here
@@ -94,6 +99,18 @@ function isSecretPathArg(t) {
 // every tool's flag surface, just the common file-value shapes.
 const VALUE_FLAGS = new Set(['-f', '--file']);
 
+// #180: `docker run --env-file .env img` / `docker compose --env-file
+// .env.prod up` / `podman run --env-file=.env img` are false positives. The
+// CONTAINER RUNTIME reads that file directly to populate the container's
+// environment; its contents never pass through the agent, so it is not a
+// secret READ by the agent (unlike a bare `cat .env`, which is). Scoped
+// narrowly: only the value of `--env-file` is exempt, and only for these
+// verbs; every other flag/positional in the same statement (image name,
+// `-v`, trailing `cat .env`, etc.) is still scanned exactly as before.
+const ENV_FILE_EXEMPT_VERBS = new Set(['docker', 'podman', 'docker-compose', 'podman-compose']);
+const ENV_FILE_EXEMPT_FLAGS = new Set(['--env-file']);
+const NO_EXEMPT_FLAGS = new Set();
+
 // The pattern-first search verbs (grep/rg/ag/sed/awk), shared with
 // trailhead-search-guard.js. Their first positional is a PATTERN, not a file
 // operand, so it must be skipped before scanning for a secret FILE argument
@@ -119,8 +136,11 @@ function stripTrailingPunct(t) {
 // Scan one already-tokenized statement's argument tokens (verb NOT stripped)
 // for a secret path used as a plain positional, an option value
 // (`--file=.env`, `-f .env`, glued `-f.env`), or a `<` (or glued `<file`)
-// redirect target. Returns the offending token or null.
-function scanTokensForSecretPath(tokens) {
+// redirect target. Returns the offending token or null. `exemptFlags` (#180)
+// names flags whose value must be skipped entirely rather than scanned, in
+// both the `--flag=value` and spaced `--flag value` forms.
+function scanTokensForSecretPath(tokens, exemptFlags) {
+  const exempt = exemptFlags || NO_EXEMPT_FLAGS;
   for (let i = 0; i < tokens.length; i++) {
     const t = stripTrailingPunct(tokens[i]);
     if (!t) continue;
@@ -143,10 +163,15 @@ function scanTokensForSecretPath(tokens) {
       // `--flag=value` form.
       const eq = t.indexOf('=');
       if (eq > 0) {
+        const flagName = t.slice(0, eq);
+        if (exempt.has(flagName)) continue; // #180: value never scanned
         const val = t.slice(eq + 1);
         if (isSecretPathArg(val)) return val;
         continue;
       }
+      // #180: exempt flag's separate-token value is skipped entirely, not
+      // scanned as a plain positional on the next loop iteration.
+      if (exempt.has(t)) { i++; continue; }
       // `-f value` / `--file value` (separate-token value).
       if (VALUE_FLAGS.has(t)) {
         const next = i + 1 < tokens.length ? stripTrailingPunct(tokens[i + 1]) : null;
@@ -214,7 +239,11 @@ function scanStatementForSecretPath(stmt) {
   if (SEARCH_VERBS.has(bin)) {
     return scanArgsSkippingPattern(tokens.slice(1), SEARCH_VERB_CONFIG[bin], isSecretPathArg);
   }
-  return scanTokensForSecretPath(tokens);
+  // #180: docker/podman (incl. `docker compose` as a subcommand, and the
+  // standalone docker-compose/podman-compose binaries) get --env-file's value
+  // exempted; every other verb keeps today's behaviour unchanged.
+  const exempt = ENV_FILE_EXEMPT_VERBS.has(bin) ? ENV_FILE_EXEMPT_FLAGS : NO_EXEMPT_FLAGS;
+  return scanTokensForSecretPath(tokens, exempt);
 }
 
 // Walk the command's top-level statements (quote-aware; `|`, `;`, `&&`,