@marcomigozzi/trailhead 0.11.0 → 0.11.1

package/bin/trailhead.js

@@ -248,10 +248,12 @@ const HOOK_FILES = ['trailhead-commit-guard.js', 'trailhead-issue-injection-scan
 // require('./lib/commit-message-check.js'); trailhead-search-guard.js and
 // trailhead-secret-read-guard.js both do require('./lib/shell-scan.js'), #135
 // follow-up; trailhead-body-guard.js and trailhead-secret-guard.js both do
-// require('./lib/gh-subcommand.js'), #153 follow-up). Copied by name, never a
-// recursive sweep: the Claude hooks/lib dir is shared with other plugins, so
-// we must not clobber a co-tenant's lib nor ship our own *.test.js files.
-const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js'];
+// require('./lib/gh-subcommand.js'), #153 follow-up; trailhead-check-update.js
+// does require('./lib/model-defaults-review.js'), which in turn reads the
+// sibling model-defaults.json, #186). Copied by name, never a recursive
+// sweep: the Claude hooks/lib dir is shared with other plugins, so we must
+// not clobber a co-tenant's lib nor ship our own *.test.js files.
+const HOOK_LIB_FILES = ['commit-message-check.js', 'shell-scan.js', 'gh-subcommand.js', 'model-defaults-review.js', 'model-defaults.json'];
 // search-guard is Claude-Code-specific (#169): excluded from both the Codex
 // hook copy and the Codex verify spec's expected hookFiles, so a healthy
 // Codex install is never flagged for a script it never ships.

package/bin/trailhead.test.js

@@ -52,6 +52,39 @@ function fakeBinDir(names) {
   return dir;
 }
 
+// #187: the pinned-model review's documented lib path (see load-first.md) is
+// relative to a skills/_shared/ dir; assert it actually resolves on every
+// install layout, survives realpathSync, and its check/ack CLI round-trips.
+const MODEL_DEFAULTS_LIB_CANDIDATES = [
+  '../../hooks/lib/model-defaults-review.js',
+  '../trailhead/hooks/lib/model-defaults-review.js',
+];
+function assertModelDefaultsLibLayout(label, sharedDir) {
+  const resolved = MODEL_DEFAULTS_LIB_CANDIDATES
+    .map((c) => path.join(sharedDir, c))
+    .find((p) => fs.existsSync(p));
+  ok(`${label}: documented model-defaults-review.js lib path resolves`, !!resolved);
+  if (!resolved) return;
+  ok(`${label}: resolved lib path still resolves after realpathSync`,
+    fs.existsSync(fs.realpathSync(resolved)));
+
+  const tmpProject = mktmp();
+  fs.mkdirSync(path.join(tmpProject, '.trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(tmpProject, '.trailhead', 'config.json'),
+    JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+
+  const noticeOut = String(execFileSync(process.execPath, [resolved, 'check', tmpProject], { encoding: 'utf8' }));
+  ok(`${label}: CLI check prints a notice`, noticeOut.trim().length > 0 && noticeOut.includes('models.plan'));
+
+  execFileSync(process.execPath, [resolved, 'ack', tmpProject], { encoding: 'utf8' });
+  const afterAckOut = String(execFileSync(process.execPath, [resolved, 'check', tmpProject], { encoding: 'utf8' }));
+  ok(`${label}: CLI check prints nothing after CLI ack`, afterAckOut === '');
+}
+
+// Source/plugin layout itself (not an installed copy), so drift is caught
+// even before an install is exercised.
+assertModelDefaultsLibLayout('source', path.join(repoRoot, 'plugins', 'trailhead', 'skills', '_shared'));
+
 // --- codex install -----------------------------------------------------------
 const codexDir = mktmp();
 const codexInstallOut = String(runInstaller([`--codex`, `--dir=${codexDir}`]));
@@ -212,8 +245,8 @@ ok('source: trailhead-chart SKILL.md config-offer points at the next-step block'
 // (session-handoff.md legitimately offers /trailhead:quick <n> for the next loose ticket).
 const captureSource = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-capture', 'references', 'capture.md'), 'utf8');
 ok('source: capture.md confirmation anchors the next step to /trailhead:work', /[Aa]nchor the next step to `\/trailhead:work <n>`, always/.test(captureSource));
-ok('source: capture.md demotes /trailhead:quick to only the no-split alternative, after the work anchor',
-  /[Aa]nchor the next step to `\/trailhead:work <n>`[\s\S]{0,400}`\/trailhead:quick <n>` is \*\*only\*\* the no-split alternative/.test(captureSource));
+ok('source: capture.md offers /trailhead:quick as the lighter alternative, after the work anchor',
+  /[Aa]nchor the next step to `\/trailhead:work <n>`[\s\S]{0,400}`\/trailhead:quick <n>` is the \*\*lighter alternative\*\*/.test(captureSource));
 ok('source: capture.md says quick is offered alongside work, never in its place', captureSource.includes('never in its place'));
 ok('source: capture.md keeps /trailhead:work the anchor even for a whiteboard capture', /whiteboard[\s\S]{0,200}the anchor stays `\/trailhead:work <n>`/.test(captureSource));
 
@@ -244,6 +277,23 @@ ok('source: capture.md says a map ticket stays on its map', /a map ticket stays
 const ticketEnginesSourceFor179 = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead-work', 'references', 'ticket-engines.md'), 'utf8');
 ok('source: ticket-engines.md never labels quick generically as off-map', !/`quick`[^.\n]{0,40}off-map/.test(ticketEnginesSourceFor179));
 
+// --- quick is the lighter path, never "just without splitting" --------------
+// Source-level invariant: wherever a next-step suggestion characterizes quick,
+// it names what quick is for (the lighter path: always size-triaged, offers to
+// skip the heavy steps on a small change, no map book-keeping), with no-split
+// as a side note. The old "only the no-split alternative" / "same work as
+// work, without split" framing made agents tell users quick merely avoids
+// splitting.
+const dispatcherSourceForQuick = fs.readFileSync(path.join(sourceSkillsDir, 'trailhead', 'SKILL.md'), 'utf8');
+ok('source: capture.md drops the "only the no-split alternative" framing', !/only\*\* the no-split alternative/.test(captureSource));
+ok('source: session-handoff.md drops the "as the no-split alternative" framing', !sessionHandoffSource.includes('as the no-split alternative'));
+ok('source: dispatcher SKILL.md drops the "as the no-split alternative" framing', !dispatcherSourceForQuick.includes('as the no-split alternative'));
+ok('source: session-handoff.md example drops "lo stesso lavoro di `work`, senza split"', !sessionHandoffSource.includes('lo stesso lavoro di `work`, senza split'));
+ok('source: capture.md says quick offers to skip the heavy steps on a small change', /quick <n>`[\s\S]{0,400}skip the heavy steps/.test(captureSource));
+ok('source: capture.md forbids describing quick as merely avoiding a split', /never as merely "without splitting"/.test(captureSource));
+ok('source: session-handoff.md forbids describing quick as merely avoiding a split', /never as merely "without splitting"/.test(sessionHandoffSource));
+ok('source: session-handoff.md example renders quick as the lighter path', /> - oppure `\/trailhead:quick[^\n]*percorso leggero/.test(sessionHandoffSource));
+
 // --- #181: scope code review and verify to the ticket's own commits ---------
 // Source-level invariant: Code review and Goal-backward verification scope to
 // the commits carrying this ticket's `Refs: #<n>` trailer (the "Ticket diff"
@@ -622,6 +672,10 @@ ok('codex: skills/trailhead/hooks/lib/commit-message-check.js exists (commit-gua
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'commit-message-check.js')));
 ok('codex: skills/trailhead/hooks/lib/gh-subcommand.js exists (body-guard/secret-guard require target, #153)',
   fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'gh-subcommand.js')));
+ok('codex: skills/trailhead/hooks/lib/model-defaults-review.js exists (check-update require target, #186)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'model-defaults-review.js')));
+ok('codex: skills/trailhead/hooks/lib/model-defaults.json exists (#186)',
+  fs.existsSync(path.join(codexDir, 'skills', 'trailhead', 'hooks', 'lib', 'model-defaults.json')));
 // #169: search-guard is Claude-Code-specific (it only prevents arming
 // Claude's Read() deny rule under bypass permissions, a mechanism Codex
 // lacks), so it must neither be registered nor copied on a Codex install.
@@ -648,6 +702,8 @@ ok('codex: trailhead-codebase-map.toml is projected with no models.codex.* set',
 ok('codex: trailhead-fix.toml is pin-less (no model = line) with no models.codex.* set',
   fs.existsSync(noPinFixTomlPath) && !/^model = /m.test(fs.readFileSync(noPinFixTomlPath, 'utf8')));
 
+assertModelDefaultsLibLayout('codex copy', path.join(codexDir, 'skills', '_shared'));
+
 // --- codex --symlink: link verbatim artifacts (hooks + templates), keep skills projected ---
 const codexSymDir = mktmp();
 runInstaller([`--codex`, `--symlink`, `--dir=${codexSymDir}`]);
@@ -672,6 +728,8 @@ ok('codex copy: hooks are regular files (not symlinks)',
 ok('codex copy: templates is a regular dir (not a symlink)',
   !fs.lstatSync(path.join(codexDir, 'skills', 'trailhead', 'templates')).isSymbolicLink());
 
+assertModelDefaultsLibLayout('codex symlink', path.join(codexSymDir, 'skills', '_shared'));
+
 // --- codex agent TOML projection (#38, #88) -------------------------------------
 // With NO models.codex.* set, a codex install still projects all 8 agents
 // uniformly, pin-less (uniform projection, #88), never zero. Install from an
@@ -765,6 +823,10 @@ ok('claude: hooks/lib/commit-message-check.js exists (commit-guard require targe
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'commit-message-check.js')));
 ok('claude: hooks/lib/gh-subcommand.js exists (body-guard/secret-guard require target, #153)',
   fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'gh-subcommand.js')));
+ok('claude: hooks/lib/model-defaults-review.js exists (check-update require target, #186)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-defaults-review.js')));
+ok('claude: hooks/lib/model-defaults.json exists (#186)',
+  fs.existsSync(path.join(claudeDir, 'hooks', 'lib', 'model-defaults.json')));
 
 // #185: the commit-msg hook sync script ships wholesale with templates/ too.
 const claudeCommitMsgSync = path.join(claudeDir, 'trailhead', 'templates', 'trailhead-commit-msg-sync.js');
@@ -800,6 +862,8 @@ ok('claude: agent file registers its subagent name in frontmatter',
 ok('claude: agents are real files on a copy install (not symlinks)',
   !fs.lstatSync(path.join(claudeAgentsDir, 'trailhead-plan.md')).isSymbolicLink());
 
+assertModelDefaultsLibLayout('claude copy', path.join(claudeDir, 'skills', '_shared'));
+
 // --- claude --symlink: dev install links hooks live too (not just skills/commands) ---
 const symDir = mktmp();
 runInstaller([`--claude`, `--symlink`, `--dir=${symDir}`]);
@@ -833,6 +897,8 @@ ok('claude symlink: agent symlink resolves into the package source',
 ok('claude copy: hooks/trailhead-secret-guard.js is a regular file (not a symlink)',
   !fs.lstatSync(path.join(claudeDir, 'hooks', 'trailhead-secret-guard.js')).isSymbolicLink());
 
+assertModelDefaultsLibLayout('claude symlink', path.join(symDir, 'skills', '_shared'));
+
 // --- claude migration: reinstall over an old layout sweeps stale skill dirs ---
 // An old install may carry a pre-split monolith (skills/trailhead-monolith) or a
 // removed cluster (skills/trailhead-legacy) the current install no longer ships.
@@ -1043,6 +1109,28 @@ for (const [label, src] of [
   ok(`source: ${label} has no em-dash`, !src.includes('—'));
 }
 
+// --- #189: script mancante / errore node -> fallback che ispeziona la hooks dir
+// invece di dichiarare alla cieca "git non applica le regole" ------------------
+ok('source: teamwork.md fallback resolves the hooks dir via rev-parse --git-path hooks',
+  teamworkSource.includes('git -C <working-root> rev-parse --git-path hooks'));
+ok('source: teamwork.md fallback classifies by the trailhead header line',
+  teamworkSource.includes('// trailhead commit-msg hook (git).'));
+ok('source: teamwork.md fallback checks the executable bit (test -x)',
+  teamworkSource.includes('test -x'));
+ok('source: teamwork.md fallback reads only the first 5 lines',
+  teamworkSource.includes('first 5 lines'));
+ok('source: teamwork.md fallback treats a symlinked commit-msg as foreign',
+  teamworkSource.includes('symlinked `commit-msg`'));
+for (const [label, src] of [
+  ['trailhead-work/SKILL.md', workSkillSource],
+  ['substrate-commands.md', substrateCommandsSource],
+]) {
+  ok(`source: ${label} mentions the missing-script hooks-dir fallback`,
+    src.includes('rev-parse --git-path hooks') && /missing script or a node error|script is missing or node errors/.test(src));
+  ok(`source: ${label} has no em-dash (#189)`, !src.includes('—'));
+}
+ok('source: teamwork.md has no em-dash (#189)', !teamworkSource.includes('—'));
+
 // --- #182 ---------------------------------------------------------------------
 // A broken install fails loudly (verifyInstall names the gap and the run exits
 // non-zero, printing no "✓ trailhead installed"); a clean one still prints ✓.
@@ -1247,6 +1335,26 @@ for (const [label, src] of [
   ok(`${label} has no em-dash (#183)`, !src.includes('\u2014'));
 }
 
+// --- plan-review: "run until it converges" option at the rounds-exhausted ask ---
+const planReviewSourceConv = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'techniques', 'plan-review.md'), 'utf8');
+const planReviewStep4 = planReviewSourceConv.split('\n').find((l) => l.startsWith('4. **Record and decide.**')) || '';
+ok('plan-review.md step 4 still offers another bounded review cycle', planReviewStep4.includes('run another review cycle'));
+ok('plan-review.md step 4 offers running until the plan converges', /\(d\) \*\*run until it converges\*\*/.test(planReviewStep4));
+ok('plan-review.md converge option stops when no blocking concern remains', /run until it converges[\s\S]{0,400}no blocking concern remains/.test(planReviewStep4));
+ok('plan-review.md converge option has a no-progress guard that returns to this checkpoint',
+  /run until it converges[\s\S]{0,600}no progress[\s\S]{0,300}back to this checkpoint/.test(planReviewStep4));
+ok('plan-review.md step 4 has no em-dash', !planReviewStep4.includes('\u2014'));
+
+// --- code-review: "run until it converges" option at the rounds-exhausted ask ---
+const codeReviewSourceConv = fs.readFileSync(path.join(sourceSkillsDir, '_shared', 'techniques', 'code-review.md'), 'utf8');
+const codeReviewBoundary = codeReviewSourceConv.split('\n').find((l) => l.startsWith('**Converge on the blockers')) || '';
+ok('code-review.md boundary ask still offers another 2 review rounds', codeReviewBoundary.includes('run another 2 review rounds'));
+ok('code-review.md boundary ask offers running until it converges', /\(c\) \*\*run until it converges\*\*/.test(codeReviewBoundary));
+ok('code-review.md converge option stops when no Critical remains', /run until it converges[\s\S]{0,400}no Critical remains/.test(codeReviewBoundary));
+ok('code-review.md converge option has a no-progress guard that returns to this checkpoint',
+  /run until it converges[\s\S]{0,600}no progress[\s\S]{0,300}back to this checkpoint/.test(codeReviewBoundary));
+ok('code-review.md boundary ask has no em-dash', !codeReviewBoundary.includes('\u2014'));
+
 // --- cleanup -------------------------------------------------------------------
 for (const d of tmpDirs) {
   fs.rmSync(d, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

package/plugins/trailhead/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "trailhead",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues, resolving one at a time. Map-based onboarding + a discuss→plan→execute→verify engine with atomic commits, all on the Issues. Ships as a dispatcher plus cohesion-clustered skills over a shared core; depends on nothing beyond an authenticated gh CLI.",
   "author": {
     "name": "Marco Migozzi",

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

@@ -0,0 +1,399 @@
+'use strict';
+// model-defaults-review.js: quando un aggiornamento sposta i default dei
+// tier (plugins/trailhead/hooks/lib/model-defaults.json), offre la revisione
+// dei models.* / models.codex.* pinnati che sono rimasti ai vecchi default.
+// check() e' di sola lettura: non scrive mai l'ack, quindi ripropone la
+// notice finche' qualcuno non chiama ack(cwd) (dopo che l'utente ha risposto
+// a una delle tre scelte). Non lancia mai eccezioni dagli entry point
+// pubblici: ogni funzione degrada a null/[]/false in caso di dato mancante
+// o malformato. Entry point condiviso anche dagli host senza hook bus (CLI
+// "check"/"ack" in fondo al file).
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DATA_FILE = path.join(__dirname, 'model-defaults.json');
+const HOSTS = ['claude', 'codex'];
+const TIERS = ['strong', 'standard', 'fast'];
+
+function isPlainObject(v) {
+  return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+
+function loadData() {
+  try {
+    return JSON.parse(fs.readFileSync(DATA_FILE, 'utf8'));
+  } catch {
+    return { schema: 1, history: [] };
+  }
+}
+
+function currentEntry(data) {
+  const history = (data && data.history) || [];
+  return history[history.length - 1] || null;
+}
+
+// Confronto semver minimale: true se a < b. Ignora pre-release, tollera "v".
+function semverLt(a, b) {
+  const clean = (v) => String(v || '').replace(/^v/, '').split('-')[0];
+  const pa = clean(a).split('.').map(Number);
+  const pb = clean(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0;
+    const y = pb[i] || 0;
+    if (x !== y) return x < y;
+  }
+  return false;
+}
+
+// Trova il tier T a cui un id e' storicamente appartenuto per un host dato:
+// T's default in una entry PIU' VECCHIA della corrente, oppure elencato nei
+// supersedes[host][T] di una qualsiasi entry (corrente inclusa). Se piu'
+// entry corrispondono, vince quella con indice piu' alto (piu' recente).
+function findTier(data, host, id, current) {
+  const history = data.history || [];
+  let best = null; // { tier, index }
+  history.forEach((entry, index) => {
+    if (entry !== current && entry[host]) {
+      for (const tier of TIERS) {
+        if (entry[host][tier] === id) {
+          if (!best || index > best.index) best = { tier, index };
+        }
+      }
+    }
+    if (entry.supersedes && entry.supersedes[host]) {
+      for (const tier of TIERS) {
+        const list = entry.supersedes[host][tier] || [];
+        if (list.includes(id)) {
+          if (!best || index > best.index) best = { tier, index };
+        }
+      }
+    }
+  });
+  return best ? best.tier : null;
+}
+
+function isSkippable(id) {
+  return !id || typeof id !== 'string' || id.trim() === '' || id === 'inherit session';
+}
+
+// Valuta un singolo pin (id) per un host e ritorna { from, to } se stale,
+// null altrimenti (id sconosciuto o gia' allineato al default corrente).
+function evaluatePin(data, host, id, current) {
+  if (isSkippable(id)) return null;
+  const tier = findTier(data, host, id, current);
+  if (!tier) return null;
+  const to = current[host][tier];
+  if (to === id) return null;
+  return { from: id, to };
+}
+
+function stalePins(config, data) {
+  const out = [];
+  const current = currentEntry(data);
+  if (!current) return out;
+  const models = (config && config.models) || {};
+
+  for (const key of Object.keys(models)) {
+    if (key === 'codex') continue;
+    const result = evaluatePin(data, 'claude', models[key], current);
+    if (result) out.push({ key: `models.${key}`, from: result.from, to: result.to });
+  }
+
+  // Un models.codex malformato (non un oggetto piano) non produce pin: come
+  // se fosse assente, invece di iterare i suoi indici/caratteri.
+  const codex = isPlainObject(models.codex) ? models.codex : {};
+  for (const key of Object.keys(codex)) {
+    const raw = codex[key];
+    const id = raw && typeof raw === 'object' ? raw.model : raw;
+    const result = evaluatePin(data, 'codex', id, current);
+    if (result) out.push({ key: `models.codex.${key}`, from: result.from, to: result.to });
+  }
+
+  return out;
+}
+
+// Ritorna una NUOVA config con i pin stale aggiornati; non muta l'input.
+function applyUpdate(config, stale) {
+  const next = { ...config, models: { ...((config && config.models) || {}) } };
+  if (next.models.codex) next.models.codex = { ...next.models.codex };
+
+  for (const s of stale) {
+    if (s.key.startsWith('models.codex.')) {
+      const k = s.key.slice('models.codex.'.length);
+      const cur = next.models.codex[k];
+      next.models.codex[k] = cur && typeof cur === 'object' ? { ...cur, model: s.to } : s.to;
+    } else {
+      const k = s.key.slice('models.'.length);
+      next.models[k] = s.to;
+    }
+  }
+  return next;
+}
+
+// Unisce piu' layer di config (dal piu' generico al piu' specifico, es.
+// [global, project]) in una config effettiva pura: nessun input viene
+// mutato. La precedenza e' per PRESENZA della chiave, mai per verita' del
+// valore: un layer piu' specifico che imposta una chiave (anche a null, ''
+// o "inherit session") vince sempre, e il valore del layer sotto non
+// riaffiora mai. models.codex e' unito chiave per chiave solo quando sia
+// l'accumulo corrente sia il valore in arrivo sono oggetti piani; altrimenti
+// il valore del layer piu' specifico rimpiazza l'intero models.codex (un
+// models.codex malformato nel progetto produce quindi zero pin codex, non
+// un fallback al globale). Ogni layer il cui `models` non e' un oggetto
+// piano (null, array, stringa) non contribuisce, come se fosse assente.
+// Ritorna { config, sources }, dove sources mappa ogni chiave vincente
+// (es. "models.plan", "models.codex.plan") a { layer, file } di chi l'ha
+// decisa, cosi' la notice puo' stampare il path reale.
+function effectiveModels(layers) {
+  let models = {};
+  let codex; // undefined finche' nessun layer tocca models.codex
+  const sources = {};
+
+  for (const layer of layers || []) {
+    const cfgModels = layer && layer.config && isPlainObject(layer.config.models) ? layer.config.models : null;
+    if (!cfgModels) continue;
+
+    for (const key of Object.keys(cfgModels)) {
+      if (key === 'codex') continue;
+      models = { ...models, [key]: cfgModels[key] };
+      sources[`models.${key}`] = { layer: layer.layer, file: layer.file };
+    }
+
+    if (Object.prototype.hasOwnProperty.call(cfgModels, 'codex')) {
+      const incoming = cfgModels.codex;
+      if (isPlainObject(incoming) && isPlainObject(codex)) {
+        for (const k of Object.keys(incoming)) {
+          codex = { ...codex, [k]: incoming[k] };
+          sources[`models.codex.${k}`] = { layer: layer.layer, file: layer.file };
+        }
+      } else {
+        for (const k of Object.keys(sources)) {
+          if (k.startsWith('models.codex.')) delete sources[k];
+        }
+        codex = isPlainObject(incoming) ? { ...incoming } : incoming;
+        if (isPlainObject(codex)) {
+          for (const k of Object.keys(codex)) {
+            sources[`models.codex.${k}`] = { layer: layer.layer, file: layer.file };
+          }
+        }
+      }
+    }
+  }
+
+  const outModels = { ...models };
+  if (codex !== undefined) outModels.codex = codex;
+  return { config: { models: outModels }, sources };
+}
+
+function reviewOffer({ config, data, ack, sources }) {
+  const current = currentEntry(data);
+  if (!current) return null;
+  const stale = stalePins(config, data).map((s) => {
+    const source = sources && sources[s.key];
+    return source ? { ...s, source } : s;
+  });
+  if (!stale.length) return null;
+  if (ack && !semverLt(ack, current.since)) return null;
+  return { since: current.since, stale, notice: reviewNotice(stale, current.since) };
+}
+
+function sourceSuffix(source) {
+  if (!source) return ' (new default)';
+  const layerName = source.layer === 'global' ? 'the global config' : 'the project config';
+  return ` (new default; from ${layerName}, ${source.file})`;
+}
+
+function reviewNotice(stale, since) {
+  const lines = stale.map((s) => `- ${s.key}: ${s.from} -> ${s.to}${sourceSuffix(s.source)}`);
+  return [
+    `trailhead's default models changed in ${since}. The following pinned model(s) are older than the new default:`,
+    ...lines,
+    '',
+    'Offer the user, once, without blocking their current request, three choices:',
+    '1) update those keys to the new defaults (edit each key in the config file it comes from, with exactly the values above; keep any codex effort unchanged),',
+    '2) keep them as they are (nothing to do; trailhead will not ask again for these defaults once acknowledged),',
+    '3) open /trailhead:config to pick per key.',
+    'This offer reappears every time it is checked until acknowledged: run the ack instruction below only after the user has picked one of the three choices above.',
+  ].join('\n');
+}
+
+// Paragrafo con l'istruzione pronta all'uso per acquisire l'ack, appesa alla
+// notice da check(). Nomina il path assoluto di questo lib e la root (la
+// root del progetto trovata, oppure il cwd nel caso solo-globale), cosi'
+// l'agente puo' eseguirla cosi' com'e'.
+function ackInstruction(root) {
+  return `Once the user has answered, run: node "${__filename}" ack "${root}"`;
+}
+
+// --- I/O ---------------------------------------------------------------
+const ACK_FILE = path.join('.trailhead', 'model-defaults-ack');
+const CONFIG_FILE = path.join('.trailhead', 'config.json');
+
+// Dir base della config globale: stessa risoluzione di trailhead-check-update.js.
+function globalConfigDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function globalConfigFile() {
+  return path.join(globalConfigDir(), 'trailhead', 'config.json');
+}
+
+// L'ack globale vive accanto al config.json globale, senza nidificare
+// ".trailhead" (che e' una convenzione solo di progetto).
+function globalAckFile() {
+  return path.join(globalConfigDir(), 'trailhead', 'model-defaults-ack');
+}
+
+// Mancante o malformato -> {}: non deve mai bloccare la review di progetto.
+function loadGlobalConfig() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(globalConfigFile(), 'utf8'));
+    return isPlainObject(raw) ? raw : {};
+  } catch {
+    return {};
+  }
+}
+
+function findProjectRoot(cwd) {
+  let dir = path.resolve(cwd || '.');
+  for (;;) {
+    if (fs.existsSync(path.join(dir, CONFIG_FILE))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function readAckFile(file) {
+  try {
+    return fs.readFileSync(file, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function writeAckFile(file, since) {
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(`${file}.tmp`, since);
+    fs.renameSync(`${file}.tmp`, file);
+  } catch {
+    /* mai far fallire il chiamante per un ack non scrivibile */
+  }
+}
+
+function readAck(root) {
+  return readAckFile(path.join(root, ACK_FILE));
+}
+
+function writeAck(root, since) {
+  writeAckFile(path.join(root, ACK_FILE), since);
+}
+
+// Di sola lettura: non scrive mai l'ack. Ripropone la stessa notice finche'
+// non arriva un ack esplicito via ack(cwd). Valuta i pin EFFETTIVI: la
+// config globale unita sotto quella di progetto (progetto vince chiave per
+// chiave); senza un progetto sopra cwd, valuta la sola config globale.
+function check(cwd) {
+  try {
+    const resolvedCwd = path.resolve(cwd || '.');
+    const root = findProjectRoot(cwd);
+    const data = loadData();
+    const globalFile = globalConfigFile();
+    const globalLayer = { layer: 'global', file: globalFile, config: loadGlobalConfig() };
+
+    if (root) {
+      let projectConfig;
+      try {
+        projectConfig = JSON.parse(fs.readFileSync(path.join(root, CONFIG_FILE), 'utf8'));
+      } catch {
+        return null;
+      }
+      const projectLayer = {
+        layer: 'project',
+        file: path.join(root, CONFIG_FILE),
+        config: isPlainObject(projectConfig) ? projectConfig : {},
+      };
+      const { config, sources } = effectiveModels([globalLayer, projectLayer]);
+      const ack = readAck(root);
+      const offer = reviewOffer({ config, data, ack, sources });
+      if (!offer) return null;
+      return `${offer.notice}\n${ackInstruction(root)}`;
+    }
+
+    // Nessun progetto sopra cwd: valuta la sola config globale, se esiste.
+    if (!fs.existsSync(globalFile)) return null;
+    const { config, sources } = effectiveModels([globalLayer]);
+    const ack = readAckFile(globalAckFile());
+    const offer = reviewOffer({ config, data, ack, sources });
+    if (!offer) return null;
+    return `${offer.notice}\n${ackInstruction(resolvedCwd)}`;
+  } catch {
+    return null;
+  }
+}
+
+// Scrive l'ack, con il "since" corrente dei default. Va chiamata SOLO dopo
+// che l'utente ha risposto a una delle tre scelte della notice. Progetto
+// trovato sopra cwd -> ack di progetto; altrimenti, se esiste una config
+// globale -> ack globale. True se un target e' stato trovato e la scrittura
+// tentata (un fallimento silenzioso non e' riportato, comportamento
+// invariato); false se nessun target esiste. Non lancia mai eccezioni.
+function ack(cwd) {
+  try {
+    const root = findProjectRoot(cwd);
+    const data = loadData();
+    const current = currentEntry(data);
+    if (!current) return false;
+    if (root) {
+      writeAck(root, current.since);
+      return true;
+    }
+    if (fs.existsSync(globalConfigFile())) {
+      writeAckFile(globalAckFile(), current.since);
+      return true;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  loadData,
+  currentEntry,
+  stalePins,
+  applyUpdate,
+  semverLt,
+  effectiveModels,
+  reviewOffer,
+  reviewNotice,
+  findProjectRoot,
+  globalConfigDir,
+  globalConfigFile,
+  globalAckFile,
+  readAckFile,
+  writeAckFile,
+  readAck,
+  writeAck,
+  check,
+  ack,
+};
+
+// CLI: entry point condiviso per gli host senza hook bus.
+if (require.main === module) {
+  const [cmd, cwdArg] = process.argv.slice(2);
+  try {
+    if (cmd === 'check') {
+      const notice = check(cwdArg || process.cwd());
+      if (notice) process.stdout.write(notice + '\n');
+    } else if (cmd === 'ack') {
+      ack(cwdArg || process.cwd());
+    }
+  } catch {
+    /* mai fallire da CLI */
+  }
+  process.exit(0);
+}