@marcomigozzi/trailhead 0.16.0 → 0.16.1

package/bin/lib/runtime-command-literals.test.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Test statico: nessun literal di comando Claude (`/trailhead:<verb>` o `/trailhead`
+// nudo) dentro stringhe/template del codice runtime. Gli hook lib e i template
+// vengono copiati byte-per-byte su Codex e convertToCodex riscrive solo il
+// markdown, quindi un literal qui arriverebbe cosi' com'e' a un utente Codex.
+// Usare commandForm(host, verb) (host-descriptor o helper locale della lib).
+// Run: node runtime-command-literals.test.js. Nessun framework: assert semplici.
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..', '..');
+const SCAN_DIRS = [
+  { dir: 'plugins/trailhead/hooks', skip: ['plugins/trailhead/hooks/mod'] },
+  { dir: 'plugins/trailhead/templates', skip: [] },
+  { dir: 'bin', skip: [] },
+];
+
+// Eccezioni motivate: file (relativo alla root) + sottostringa della riga.
+// Niente numeri di riga, cosi' le modifiche attorno non rompono il test.
+const ALLOWLIST = [
+  {
+    file: 'plugins/trailhead/templates/trailhead-dashboard.js',
+    contains: 'Regenerate any time with',
+    reason: 'corpo del dashboard: artefatto condiviso host-neutral scritto nell\'issue, non un messaggio runtime per host',
+  },
+  {
+    file: 'bin/trailhead.js',
+    contains: '(/trailhead:*)',
+    reason: 'banner dell\'installer Claude-only (il ramo Codex stampa il proprio banner)',
+  },
+  {
+    file: 'bin/trailhead.js',
+    contains: 'then run /trailhead to start',
+    reason: 'banner dell\'installer Claude-only',
+  },
+  {
+    file: 'bin/lib/codex-projection.js',
+    contains: 'Never \\`/trailhead:<verb>\\`',
+    reason: 'testo del SKILL.md Codex: nomina la forma Claude proprio per vietarla all\'agente',
+  },
+  {
+    file: 'bin/lib/host-descriptor.js',
+    contains: "commandPrefix: '/trailhead:'",
+    reason: 'dato del descriptor Claude da cui commandForm produce la forma Claude',
+  },
+  {
+    file: 'plugins/trailhead/hooks/lib/model-defaults-review.js',
+    contains: '`/trailhead:${verb}`',
+    reason: 'helper commandForm della lib: l\'unico punto che produce la forma Claude',
+  },
+];
+
+// `/trailhead:` (anche seguito da `${`, `*`, `<verb>` o concatenato) oppure
+// `/trailhead` nudo. Non conta dentro un path: non preceduto da parola, `.`,
+// `~`, `\`, `/`, `-` e non seguito da parola, `:`, `/`, `\`, `-`.
+const COMMAND_RE = /(?<![\w.~\\/-])\/trailhead(?::|(?![\w:/\\-]))/g;
+
+function listJs(dir, skip) {
+  const out = [];
+  for (const e of fs.readdirSync(path.join(ROOT, dir), { withFileTypes: true })) {
+    const rel = `${dir}/${e.name}`;
+    if (e.isDirectory()) {
+      if (e.name === 'node_modules' || skip.includes(rel)) continue;
+      out.push(...listJs(rel, skip));
+    } else if (e.name.endsWith('.js') && !e.name.endsWith('.test.js')) {
+      out.push(rel);
+    }
+  }
+  return out;
+}
+
+// Scanner minimale a stati sull'intero file: marca i caratteri che stanno
+// dentro stringhe ('...', "...") e template (`...`, anche su piu' righe, con i
+// loro ${...}); commenti e literal regex sono saltati. Non e' un parser JS
+// completo: una regex e' riconosciuta dal carattere significativo precedente.
+const REGEX_PREV = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '<', '>', '~', '^']);
+function literalMask(text) {
+  const mask = new Uint8Array(text.length);
+  let i = 0;
+  let prev = '';
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+    } else if (c === '/' && n === '*') {
+      const end = text.indexOf('*/', i + 2);
+      i = end === -1 ? text.length : end + 2;
+    } else if (c === '"' || c === "'" || c === '`') {
+      mask[i] = 1;
+      i++;
+      while (i < text.length && text[i] !== c) {
+        if (text[i] === '\\') { mask[i] = 1; i++; }
+        if (c !== '`' && text[i] === '\n') break;
+        mask[i] = 1;
+        i++;
+      }
+      if (i < text.length) mask[i] = 1;
+      i++;
+      prev = c;
+    } else if (c === '/' && (REGEX_PREV.has(prev) || prev === 'return')) {
+      i++;
+      let inClass = false;
+      while (i < text.length && text[i] !== '\n' && (inClass || text[i] !== '/')) {
+        if (text[i] === '\\') i++;
+        else if (text[i] === '[') inClass = true;
+        else if (text[i] === ']') inClass = false;
+        i++;
+      }
+      i++;
+      prev = ')';
+    } else {
+      if (!/\s/.test(c)) {
+        const word = /[A-Za-z_$]/.test(c) ? text.slice(i).match(/^[\w$]+/)[0] : c;
+        prev = word === 'return' ? 'return' : word.length > 1 ? 'a' : c;
+        i += word.length;
+        continue;
+      }
+      i++;
+    }
+  }
+  return mask;
+}
+
+const used = new Set();
+
+function findViolations(rel, text) {
+  const out = [];
+  const mask = literalMask(text);
+  const lines = text.split('\n');
+  const starts = [];
+  let off = 0;
+  for (const l of lines) { starts.push(off); off += l.length + 1; }
+  for (const m of text.matchAll(COMMAND_RE)) {
+    if (!mask[m.index]) continue;
+    let ln = starts.findIndex((st, k) => k === starts.length - 1 || starts[k + 1] > m.index);
+    const line = lines[ln];
+    const idx = ALLOWLIST.findIndex((a) => a.file === rel && line.includes(a.contains));
+    if (idx >= 0) { used.add(idx); continue; }
+    out.push(`${rel}:${ln + 1}: ${line.trim()}`);
+  }
+  return out;
+}
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Sanity del rilevatore: deve fermare il literal originale e ignorare i path.
+ok('detector flags the original review-offer literal',
+  findViolations('x.js', "  '3) open /trailhead:config to pick per key.',").length === 1);
+ok('detector flags a bare /trailhead in a literal',
+  findViolations('x.js', "console.log('run /trailhead to start');").length === 1);
+ok('detector ignores comment lines', findViolations('x.js', '// run /trailhead:update').length === 0);
+ok('detector ignores path segments',
+  findViolations('x.js', "path.join('skills/trailhead/hooks', 'refs/heads/trailhead/t1')").length === 0);
+ok('detector flags a concatenated literal', findViolations('x.js', "const c = '/trailhead:' + v;").length === 1);
+ok('detector flags a template literal with interpolation', findViolations('x.js', 'const c = `/trailhead:${v}`;').length === 1);
+ok('detector flags a literal on a later line of a multi-line template',
+  findViolations('x.js', 'const t = `first line\nrun /trailhead:config now`;').length === 1);
+ok('detector flags the glob and placeholder forms',
+  findViolations('x.js', "a('/trailhead:*'); b('/trailhead:<verb>');").length === 2);
+ok('detector ignores a regex literal with an escaped slash',
+  findViolations('x.js', "const R = /^refs\\/heads\\/trailhead\\/t(\\d+)$/; const q = /['\"]/;").length === 0);
+ok('detector ignores the host-neutral helper form',
+  findViolations('x.js', 'const c = commandForm(host, "config");').length === 0);
+
+// Le eccezioni in allowlist devono ancora corrispondere a qualcosa.
+for (const a of ALLOWLIST) {
+  ok(`allowlist file exists: ${a.file}`, fs.existsSync(path.join(ROOT, a.file)));
+  ok(`allowlist reason given: ${a.file}`, a.reason.length > 0);
+}
+
+const files = SCAN_DIRS.flatMap(({ dir, skip }) => listJs(dir, skip));
+ok('scan covers hook libs, templates and bin', files.length > 20);
+const violations = files.flatMap((rel) => findViolations(rel, fs.readFileSync(path.join(ROOT, rel), 'utf8')));
+assert.deepStrictEqual(violations, [],
+  `literal di comando Claude in codice runtime (usa commandForm):\n${violations.join('\n')}`);
+passed++;
+const unused = ALLOWLIST.filter((_, i) => !used.has(i)).map((a) => `${a.file}: ${a.contains}`);
+assert.deepStrictEqual(unused, [], `voci di allowlist mai usate (da rimuovere):\n${unused.join('\n')}`);
+passed++;
+
+console.log(`runtime-command-literals.test.js: ${passed} assertions passed`);

package/bin/report-status-docs.test.js

@@ -48,7 +48,7 @@ ok('the checker command with its technique flag and a report file',
 ok('the three templates dirs, in order',
   (() => {
     const a = para.indexOf('${CLAUDE_PLUGIN_ROOT}/templates/');
-    const b = para.indexOf('~/.claude/trailhead/templates/');
+    const b = para.indexOf('${CLAUDE_CONFIG_DIR:-~/.claude}/trailhead/templates/');
     const c = para.indexOf('~/.codex/skills/trailhead/templates/');
     return a !== -1 && b > a && c > b;
   })());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.16.0",
+  "version": "0.16.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.16.0",
+  "version": "0.16.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/agents/trailhead-code-review.md

@@ -19,7 +19,7 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 <!-- trailhead:agent-block reviewing -->
 **Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts the `VERIFY` comment after it checks the status line.
 - The first line of the report is the technique's `status:` line, verbatim: `status: <token>`, with nothing before it and no other `status:` line.
-- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`.
-- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`.
+- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
+- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
 <!-- /trailhead:agent-block reviewing -->

package/plugins/trailhead/agents/trailhead-verify.md

@@ -19,7 +19,7 @@ Never `cd` (or `pushd`/`env -C`) into a directory first; the full rule is in `_s
 <!-- trailhead:agent-block reviewing -->
 **Return contract.** Return the complete report as your final message. Do not post it anywhere (no issue comment, no PR comment): the orchestrator posts the `VERIFY` comment after it checks the status line.
 - The first line of the report is the technique's `status:` line, verbatim: `status: <token>`, with nothing before it and no other `status:` line.
-- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`.
-- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`.
+- trailhead-verify: `<token>` is one of `met` | `gaps_found` | `inconclusive`; each claim line carries `class: <met|unmet|partial|inconclusive>`, and `met` lists no `unmet`, `partial` or `inconclusive` claim.
+- trailhead-code-review: `<token>` is one of `clean` | `issues_found`, and line 2 is the counts line `critical: <n> · warning: <n> · info: <n>`; `clean` with a non-zero `critical` count requires a ledger line closing every Critical (`fixed`, `deferred` or `accepted`), none `open`.
 - Read-only: never Edit/Write, never commit.
 <!-- /trailhead:agent-block reviewing -->

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

@@ -17,6 +17,25 @@ const DATA_FILE = path.join(__dirname, 'model-defaults.json');
 const HOSTS = ['claude', 'codex'];
 const TIERS = ['strong', 'standard', 'fast'];
 
+// Host: la lib viene copiata byte-per-byte su Codex (sotto
+// <codexHome>/skills/trailhead/hooks/lib), quindi l'host si deduce dal path
+// installato, senza env (stessa idea di trailhead-check-update.js). Un
+// argomento `host` esplicito sovrascrive la rilevazione (test, host futuri).
+const CODEX_LIB_RE = /[\\/]skills[\\/]trailhead[\\/]hooks[\\/]lib$/;
+
+function detectHost(dir = __dirname) {
+  return CODEX_LIB_RE.test(dir) ? 'codex' : 'claude';
+}
+
+function normalizeHost(host) {
+  return HOSTS.includes(host) ? host : detectHost();
+}
+
+// Forma del comando per host: `/trailhead:<verb>` su Claude, `$trailhead <verb>` su Codex.
+function commandForm(host, verb) {
+  return normalizeHost(host) === 'codex' ? `$trailhead ${verb}` : `/trailhead:${verb}`;
+}
+
 function isPlainObject(v) {
   return !!v && typeof v === 'object' && !Array.isArray(v);
 }
@@ -187,7 +206,7 @@ function effectiveModels(layers) {
   return { config: { models: outModels }, sources };
 }
 
-function reviewOffer({ config, data, ack, sources }) {
+function reviewOffer({ config, data, ack, sources, host }) {
   const current = currentEntry(data);
   if (!current) return null;
   const stale = stalePins(config, data).map((s) => {
@@ -196,7 +215,7 @@ function reviewOffer({ config, data, ack, sources }) {
   });
   if (!stale.length) return null;
   if (ack && !semverLt(ack, current.since)) return null;
-  return { since: current.since, stale, notice: reviewNotice(stale, current.since) };
+  return { since: current.since, stale, notice: reviewNotice(stale, current.since, host) };
 }
 
 function sourceSuffix(source) {
@@ -205,7 +224,7 @@ function sourceSuffix(source) {
   return ` (new default; from ${layerName}, ${source.file})`;
 }
 
-function reviewNotice(stale, since) {
+function reviewNotice(stale, since, host) {
   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:`,
@@ -214,7 +233,7 @@ function reviewNotice(stale, since) {
     '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.',
+    `3) open ${commandForm(host, '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');
 }
@@ -231,25 +250,33 @@ function ackInstruction(root) {
 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() {
+// Dir base della config globale. Claude: CLAUDE_CONFIG_DIR o ~/.claude (come
+// trailhead-check-update.js).
+// Su Codex e' <codexHome>, ricavato dal path installato della lib (4 livelli
+// sopra __dirname: <codexHome>/skills/trailhead/hooks/lib); con host forzato
+// fuori da un'installazione Codex ripiega su CODEX_HOME o ~/.codex.
+function globalConfigDir(host) {
+  if (normalizeHost(host) === 'codex') {
+    if (detectHost() === 'codex') return path.resolve(__dirname, '..', '..', '..', '..');
+    return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+  }
   return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
 }
 
-function globalConfigFile() {
-  return path.join(globalConfigDir(), 'trailhead', 'config.json');
+function globalConfigFile(host) {
+  return path.join(globalConfigDir(host), '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');
+function globalAckFile(host) {
+  return path.join(globalConfigDir(host), 'trailhead', 'model-defaults-ack');
 }
 
 // Mancante o malformato -> {}: non deve mai bloccare la review di progetto.
-function loadGlobalConfig() {
+function loadGlobalConfig(host) {
   try {
-    const raw = JSON.parse(fs.readFileSync(globalConfigFile(), 'utf8'));
+    const raw = JSON.parse(fs.readFileSync(globalConfigFile(host), 'utf8'));
     return isPlainObject(raw) ? raw : {};
   } catch {
     return {};
@@ -296,13 +323,13 @@ function writeAck(root, since) {
 // 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) {
+function check(cwd, { host } = {}) {
   try {
     const resolvedCwd = path.resolve(cwd || '.');
     const root = findProjectRoot(cwd);
     const data = loadData();
-    const globalFile = globalConfigFile();
-    const globalLayer = { layer: 'global', file: globalFile, config: loadGlobalConfig() };
+    const globalFile = globalConfigFile(host);
+    const globalLayer = { layer: 'global', file: globalFile, config: loadGlobalConfig(host) };
 
     if (root) {
       let projectConfig;
@@ -318,7 +345,7 @@ function check(cwd) {
       };
       const { config, sources } = effectiveModels([globalLayer, projectLayer]);
       const ack = readAck(root);
-      const offer = reviewOffer({ config, data, ack, sources });
+      const offer = reviewOffer({ config, data, ack, sources, host });
       if (!offer) return null;
       return `${offer.notice}\n${ackInstruction(root)}`;
     }
@@ -326,8 +353,8 @@ function check(cwd) {
     // 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 });
+    const ack = readAckFile(globalAckFile(host));
+    const offer = reviewOffer({ config, data, ack, sources, host });
     if (!offer) return null;
     return `${offer.notice}\n${ackInstruction(resolvedCwd)}`;
   } catch {
@@ -341,7 +368,7 @@ function check(cwd) {
 // 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) {
+function ack(cwd, { host } = {}) {
   try {
     const root = findProjectRoot(cwd);
     const data = loadData();
@@ -351,8 +378,8 @@ function ack(cwd) {
       writeAck(root, current.since);
       return true;
     }
-    if (fs.existsSync(globalConfigFile())) {
-      writeAckFile(globalAckFile(), current.since);
+    if (fs.existsSync(globalConfigFile(host))) {
+      writeAckFile(globalAckFile(host), current.since);
       return true;
     }
     return false;
@@ -370,6 +397,8 @@ module.exports = {
   effectiveModels,
   reviewOffer,
   reviewNotice,
+  detectHost,
+  commandForm,
   findProjectRoot,
   globalConfigDir,
   globalConfigFile,

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

@@ -480,6 +480,56 @@ ok('stalePins: a non-object models.codex yields no codex pins (not an exception)
     ackOut === '' && fs.existsSync(path.join(globalDir, 'trailhead', 'model-defaults-ack')));
 }
 
+// --- host-aware command form e global config (Codex) --------------------
+{
+  const stale = [{ key: 'models.plan', from: 'claude-opus-4-8', to: 'claude-opus-5-5' }];
+  const codexNotice = reviewNotice(stale, cur.since, 'codex');
+  const claudeNotice = reviewNotice(stale, cur.since, 'claude');
+  ok('reviewNotice(codex) names $trailhead config', codexNotice.includes('open $trailhead config'));
+  ok('reviewNotice(codex) never names the Claude slash form', !codexNotice.includes('/trailhead:'));
+  ok('reviewNotice(claude) names /trailhead:config', claudeNotice.includes('open /trailhead:config'));
+  ok('reviewNotice default host is claude outside an installed Codex path',
+    reviewNotice(stale, cur.since).includes('/trailhead:config'));
+}
+
+{
+  // Lib copiata sotto un finto <codexHome>/skills/trailhead/hooks/lib/: l'host
+  // si deduce dal path, senza env, e la config globale e' <codexHome>/trailhead/.
+  const codexHome = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-codexhome-'));
+  const libDir = path.join(codexHome, 'skills', 'trailhead', 'hooks', 'lib');
+  fs.mkdirSync(libDir, { recursive: true });
+  for (const f of ['model-defaults-review.js', 'model-defaults.json']) {
+    fs.copyFileSync(path.join(__dirname, f), path.join(libDir, f));
+  }
+  fs.mkdirSync(path.join(codexHome, 'trailhead'), { recursive: true });
+  fs.writeFileSync(path.join(codexHome, 'trailhead', 'config.json'), JSON.stringify({ models: { plan: 'claude-opus-4-8' } }));
+  const noProjDir = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-codex-noproj-'));
+  const copied = path.join(libDir, 'model-defaults-review.js');
+
+  const out = execFileSync('node', [copied, 'check', noProjDir], {
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_CONFIG_DIR: BASE_CONFIG_DIR, CODEX_HOME: '' },
+  });
+  ok('Codex path: check() honours <codexHome>/trailhead/config.json', out.includes('models.plan: claude-opus-4-8 -> claude-opus-5-5'));
+  ok('Codex path: the notice offers $trailhead config', out.includes('open $trailhead config'));
+  ok('Codex path: the notice never names /trailhead:', !out.includes('/trailhead:'));
+  ok('Codex path: the notice tags the Codex global config path',
+    out.includes(path.join(codexHome, 'trailhead', 'config.json')));
+
+  execFileSync('node', [copied, 'ack', noProjDir], {
+    encoding: 'utf8',
+    env: { ...process.env, CLAUDE_CONFIG_DIR: BASE_CONFIG_DIR, CODEX_HOME: '' },
+  });
+  ok('Codex path: the global ack lands under <codexHome>/trailhead/',
+    fs.existsSync(path.join(codexHome, 'trailhead', 'model-defaults-ack')));
+
+  const mod = require(copied);
+  ok('Codex path: globalConfigDir resolves to the codexHome', mod.globalConfigDir() === codexHome);
+  ok('Codex path: check() is silenced after the Codex global ack', mod.check(noProjDir) === null);
+  ok('Claude behaviour unchanged: globalConfigDir still follows CLAUDE_CONFIG_DIR',
+    globalConfigDir() === BASE_CONFIG_DIR);
+}
+
 console.log(`model-defaults-review.test.js: ${passed} assertions passed`);
 
 if (PRIOR_CLAUDE_CONFIG_DIR === undefined) {

package/plugins/trailhead/hooks/lib/report-status.test.js

@@ -16,13 +16,15 @@ const fs = require('fs');
 const os = require('os');
 
 const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-report-status.js');
-const { checkReport, TOKENS, CONTRACTS, FAMILY_OF } = require(scriptPath);
+const { checkReport, TOKENS, CONTRACTS, FAMILY_OF, VERIFY_CLASSES } = require(scriptPath);
 const techDir = path.resolve(__dirname, '..', '..', 'skills', '_shared', 'techniques');
 
 let passed = 0;
 const ok = (name, cond) => { assert.ok(cond, name); passed++; };
 
 const K = 'critical: 0 · warning: 1 · info: 2'; // the counts line
+const K1 = 'critical: 1 · warning: 0 · info: 0';
+const K2 = 'critical: 2 · warning: 1 · info: 0';
 const V = 'verify';
 const C = 'code-review';
 const KEYS = ['action', 'verdict', 'problem', 'report', 'fields', 'body'];
@@ -119,6 +121,60 @@ const rows = [
   ['two counts lines', C, `status: clean\n${K}\nbody\n${K}\n`, ['reask', null, 'counts']],
   ['two different counts lines', C, `status: clean\n${K}\ncritical: 1 · warning: 1 · info: 2\n`, ['reask', null, 'counts']],
   ['counts only inside a code fence', C, `status: clean\n\`\`\`\n${K}\n\`\`\`\n`, ['reask', null, 'counts']],
+
+  // --- verdict vs content: code-review fails closed on an unclosed Critical ---
+  ['clean with critical 2 and no ledger (ticket repro)', C, `status: clean\n${K2}\n\n- critical: SQL injection\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\n\n- critical: SQL injection\n`]],
+  ['clean, critical 1, C1 fixed', C, `status: clean\n${K1}\nC1 fixed (abc123)\n`, ['accept', 'clean', null]],
+  ['clean, critical 1, C1 deferred', C, `status: clean\n${K1}\n- C1: deferred → #12\n`, ['accept', 'clean', null]],
+  ['clean, critical 1, C1 accepted', C, `status: clean\n${K1}\nC1 accepted: false positive\n`, ['accept', 'clean', null]],
+  ['clean, critical 2, only C1 closed', C, `status: clean\n${K2}\nC1 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\n`]],
+  ['clean, critical 1, C1 open', C, `status: clean\n${K1}\nC1 open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 open\n`]],
+  ['clean, critical 1, C1 fixed and C2 open', C, `status: clean\n${K1}\nC1 fixed (a)\nC2 open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 fixed (a)\nC2 open\n`]],
+  ['clean, critical 1, only a reclassified pointer', C, `status: clean\n${K1}\nC1 reclassified as W3\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 reclassified as W3\n`]],
+  ['clean, critical 1, ledger line only inside a fence', C, `status: clean\n${K1}\n\`\`\`\nC1 fixed (a)\n\`\`\`\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\n\`\`\`\nC1 fixed (a)\n\`\`\`\n`]],
+  ['clean, critical 2, a repeated C1 line counts once', C, `status: clean\n${K2}\nC1 fixed (a)\nc1 fixed (b)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\nc1 fixed (b)\n`]],
+  ['finding prose with open after a closed ledger line stays clean', C, `status: clean\n${K1}\nC1: fixed (abc)\nC1 file.js:3 handler leaves the socket open\n`, ['accept', 'clean', null]],
+  ['open redirect prose with a fixed ledger stays clean', C, `status: clean\n${K1}\nC1 fixed (abc)\nC1 open redirect in login.js:9\n`, ['accept', 'clean', null]],
+  ['a lone fixed-size prose line does not close the Critical', C, `status: clean\n${K1}\nC1 fixed-size buffer overflow in x.js:3: open\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 fixed-size buffer overflow in x.js:3: open\n`]],
+  ['bold id and en-dash separator ledger line', C, `status: clean\n${K1}\n- **C1** – fixed (abc)\n`, ['accept', 'clean', null]],
+  ['verify subclass is not a class line', V, 'status: met\n- a, subclass: unmet\n', ['accept', 'met', null]],
+  ['an unparsed open line for an uncounted Critical fails closed', C, `status: clean\n${K2}\nC1 fixed (a)\nC2 fixed (b)\nC3 open because x\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K2}\nC1 fixed (a)\nC2 fixed (b)\nC3 open because x\n`]],
+  ['em dash separator closes the Critical', C, `status: clean\n${K1}\nC1 ${String.fromCharCode(0x2014)} fixed (abc)\n`, ['accept', 'clean', null]],
+  ['still open fails closed', C, `status: clean\n${K1}\nC1: still open\nC2 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1: still open\nC2 fixed (a)\n`]],
+  ['bracketed open fails closed', C, `status: clean\n${K1}\nC1 [open]\nC2 fixed (a)\n`,
+    ['normalise', 'issues_found', null, `status: issues_found\n${K1}\nC1 [open]\nC2 fixed (a)\n`]],
+  ['a reclassified Critical does not gate the rest', C, `status: clean\n${K1}\nC1 reclassified as W3\nC2 fixed (a)\n`, ['accept', 'clean', null]],
+  ['clean, critical 0, warnings open never gate', C, `status: clean\n${K}\nW1 open\n`, ['accept', 'clean', null]],
+  ['issues_found is never changed', C, `status: issues_found\n${K1}\nC1 fixed (a)\n`, ['accept', 'issues_found', null]],
+
+  // --- verdict vs content: verify raises the tag to the highest claim class ---
+  ['verify met with a met claim', V, 'status: met\n- claim 1, class: met\n', ['accept', 'met', null]],
+  ['verify met with an unmet claim', V, 'status: met\n- Claim 2: login wired, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- Claim 2: login wired, class: unmet\n']],
+  ['verify met with a partial claim', V, 'status: met\n- claim 1, class: partial\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- claim 1, class: partial\n']],
+  ['verify met with an inconclusive claim', V, 'status: met\n- claim 1, class: inconclusive\n  reason: unrunnable-check\n',
+    ['normalise', 'inconclusive', null, 'status: inconclusive\n- claim 1, class: inconclusive\n  reason: unrunnable-check\n']],
+  ['verify met with inconclusive and unmet', V, 'status: met\n- a, class: inconclusive\n- b, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- a, class: inconclusive\n- b, class: unmet\n']],
+  ['verify inconclusive with an unmet claim', V, 'status: inconclusive\n- b, class: unmet\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- b, class: unmet\n']],
+  ['verify gaps_found with only met claims stays', V, 'status: gaps_found\n- a, class: met\n', ['accept', 'gaps_found', null]],
+  ['verify inconclusive with only met claims stays', V, 'status: inconclusive\n- a, class: met\n', ['accept', 'inconclusive', null]],
+  ['verify class line inside a fence is ignored', V, 'status: met\n```\n- a, class: unmet\n```\n', ['accept', 'met', null]],
+  ['verify class line inside a blockquote is ignored', V, 'status: met\n> - a, class: unmet\n', ['accept', 'met', null]],
+  ['verify upper-case class counts', V, 'status: met\n- a, Class: UNMET\n',
+    ['normalise', 'gaps_found', null, 'status: gaps_found\n- a, Class: UNMET\n']],
 ];
 
 for (const [name, technique, input, expected] of rows) {
@@ -274,6 +330,17 @@ ok('vocabulary: code-review tokens equal the ones code-review.md defines',
     ok(`contracts: technique ${technique} maps to the family of trailhead-${technique} in the sync script`, FAMILIES[`trailhead-${technique}`] === family);
     ok(`contracts: TOKENS.${technique} are the ${family} tokens`, JSON.stringify(TOKENS[technique]) === JSON.stringify(CONTRACTS[family].tokens));
   }
+  // the reviewing block names the verify class vocabulary and the closing dispositions
+  const bullet = (block, prefix) => block.split('\n').find((l) => l.startsWith(`- ${prefix}:`)) || '';
+  const classTokens = (text) => [...text.matchAll(/class: <([a-z|]+)>/g)].flatMap((m) => m[1].split('|'));
+  ok('contracts: reviewing verify bullet names the checker class vocabulary',
+    JSON.stringify(classTokens(bullet(blocks.reviewing, 'trailhead-verify'))) === JSON.stringify(VERIFY_CLASSES));
+  const crBullet = bullet(blocks.reviewing, 'trailhead-code-review');
+  ok('contracts: reviewing code-review bullet names the closing dispositions',
+    ['fixed', 'deferred', 'accepted'].every((d) => new RegExp(`\\x60${d}\\x60`).test(crBullet)));
+  const verifyDoc = fs.readFileSync(path.join(techDir, 'verify.md'), 'utf8');
+  ok('contracts: verify.md names the same class vocabulary',
+    classTokens(verifyDoc.replace(/class: ([a-z]+(?: \| [a-z]+)+)/g, (m, g) => `class: <${g.replace(/ \| /g, '|')}>`)).join() === VERIFY_CLASSES.join());
   ok('contracts: every non-review agent has a technique here',
     Object.entries(FAMILIES).filter(([, f]) => f !== 'reviewing').every(([a]) => FAMILY_OF[a.replace(/^trailhead-/, '')] !== undefined));
 }

package/plugins/trailhead/hooks/lib/shell-scan.js

@@ -633,6 +633,23 @@ const SEARCH_VERB_CONFIG = {
   awk: { patternFirst: true, valueFlags: new Set(['-f', '-v']), patternFlags: new Set() },
 };
 
+// #316: the -f / --file operand of a flag token, or null when the token is not one.
+// Forms: `-f V`, `-fV`, a short cluster whose FIRST value-taking letter is `f`
+// (`-if.env`; after another value letter the rest is that flag's value, so
+// `-ef.env` is a pattern), `--file V`, `--file=V`. `consumed` = extra tokens used.
+function fileFlagOperand(t, next, config) {
+  if (t === '--file') return { value: next, consumed: 1 };
+  if (t.startsWith('--file=')) return { value: t.slice('--file='.length), consumed: 0 };
+  if (t.startsWith('--')) return null;
+  for (let i = 1; i < t.length; i++) {
+    if (!config.valueFlags.has(`-${t[i]}`)) continue;
+    if (t[i] !== 'f') return null;
+    const rest = t.slice(i + 1);
+    return rest ? { value: rest, consumed: 0 } : { value: next, consumed: 1 };
+  }
+  return null;
+}
+
 // Walk a verb's argument tokens (verb itself already stripped), skipping
 // flags (and their separate-token values), an explicit `--` end-of-options
 // marker (which must not itself swallow the next real positional), and the
@@ -647,6 +664,14 @@ function scanArgsSkippingPattern(args, config, isMatch) {
     const t = args[j];
     if (!afterDashDash && t === '--') { afterDashDash = true; continue; }
     if (!afterDashDash && t.startsWith('-') && t !== '-') {
+      // #316: the value of -f / --file is a FILE the verb reads, so it is tested.
+      const file = fileFlagOperand(t, args[j + 1], config);
+      if (file) {
+        if (file.value !== undefined && file.value !== '' && isMatch(file.value)) return file.value;
+        patternConsumed = true; // the pattern/script comes from that file, so positionals are FILEs
+        j += file.consumed;
+        continue;
+      }
       if (config.valueFlags.has(t)) {
         j++; // consume its separate-token value
         if (config.patternFlags && config.patternFlags.has(t)) patternConsumed = true;

package/plugins/trailhead/hooks/lib/statusline-context.test.js

@@ -136,5 +136,26 @@ eq('edge threshold', pct(1000, edge), 100);
 // finestra minuscola: soglia mai sotto 1
 eq('tiny window guard', pct(5, { env: { CLAUDE_CODE_AUTO_COMPACT_WINDOW: '10' } }), 100);
 
-fs.rmSync(root, { recursive: true, force: true });
+// --- credenziali: il blocco usage legge .credentials.json da CLAUDE_CONFIG_DIR (#320) ---
+// Segnale osservabile: la dir cache viene creata solo se il guard sulle credenziali passa.
+function usageReached({ withCreds }) {
+  const credCfg = path.join(root, withCreds ? 'cfg-creds' : 'cfg-nocreds');
+  const cache = path.join(root, withCreds ? 'cache-creds' : 'cache-nocreds');
+  fs.mkdirSync(credCfg, { recursive: true });
+  fs.mkdirSync(cache, { recursive: true });
+  if (withCreds) {
+    fs.writeFileSync(path.join(credCfg, '.credentials.json'), JSON.stringify({ claudeAiOauth: { accessToken: 'dummy' } }));
+  }
+  const env = { ...process.env, NO_COLOR: '1', HOME: home, CLAUDE_CONFIG_DIR: credCfg, XDG_CACHE_HOME: cache,
+    USAGE_API_TIMEOUT: '1', HTTPS_PROXY: 'http://127.0.0.1:9', https_proxy: 'http://127.0.0.1:9' };
+  delete env.TRAILHEAD_STATUSLINE_USAGE;
+  const input = { model: { id: 'claude-opus-5-5', display_name: 'Test' }, workspace: { project_dir: proj, current_dir: proj } };
+  spawnSync('bash', [script, '--context-only'], { input: JSON.stringify(input), env, encoding: 'utf8' });
+  return fs.existsSync(path.join(cache, 'trailhead-statusline'));
+}
+ok('usage block reached with creds under CLAUDE_CONFIG_DIR', usageReached({ withCreds: true }));
+ok('usage block skipped without creds', !usageReached({ withCreds: false }));
+
+// retry: il python in background puo' ancora scrivere nella cache mentre si pulisce
+fs.rmSync(root, { recursive: true, force: true, maxRetries: 3, retryDelay: 50 });
 console.log(`statusline-context.test.js: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/unmodelled.js

@@ -62,6 +62,11 @@ const WRAPPER_VALUE_FLAGS = {
   nohup: [],
 };
 
+// Is `word` (as written, quotes allowed) a command wrapper from the list above? #316
+function isWrapperWord(word) {
+  return Object.prototype.hasOwnProperty.call(WRAPPER_VALUE_FLAGS, dequote(word));
+}
+
 // Index just past a wrapper's own flags (and assignments), from the wrapper at toks[k].
 function skipWrapper(toks, k) {
   const w = dequote(toks[k]);
@@ -342,4 +347,4 @@ function unmodelledReason(guard, what, hit, redact) {
     `interpret with certainty, so it cannot verify ${what}. Rewrite it in a simple form: ${hit.hint}.`;
 }
 
-module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason };
+module.exports = { UNMODELLED, findUnmodelled, firstRelevant, unmodelledReason, isWrapperWord };