@marcomigozzi/trailhead 0.11.1 → 0.12.1

package/plugins/trailhead/hooks/lib/fixtures/label-guard-0.12.0.yml

@@ -0,0 +1,55 @@
+# trailhead label guard: repo-side enforcement.
+# Copy this file to your repository's .github/workflows/ directory.
+# It strips any `trailhead:*` label applied by an actor without write access,
+# so external / triage users (and stray automations) can't inject tickets into
+# the trailhead map. Maintainers (write/admin/maintain) apply labels normally.
+#
+# Optional: set a repo variable TRAILHEAD_LABEL_ALLOWLIST to a comma-separated
+# list of extra logins that are always allowed (e.g. a bot account trailhead runs as).
+
+name: trailhead label guard
+
+on:
+  issues:
+    types: [labeled]
+
+permissions:
+  issues: write
+
+jobs:
+  guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        env:
+          ALLOWLIST: ${{ vars.TRAILHEAD_LABEL_ALLOWLIST }}
+        with:
+          script: |
+            const label = context.payload.label && context.payload.label.name || '';
+            if (!label.startsWith('trailhead:')) return;
+
+            const actor = context.payload.sender.login;
+            const extra = (process.env.ALLOWLIST || '')
+              .split(',').map(s => s.trim().toLowerCase()).filter(Boolean);
+            if (extra.includes(actor.toLowerCase())) return;
+
+            let permission = 'none';
+            try {
+              const r = await github.rest.repos.getCollaboratorPermissionLevel({
+                owner: context.repo.owner, repo: context.repo.repo, username: actor });
+              permission = r.data.permission; // admin | write | read | none  (triage→read, maintain→write)
+            } catch (e) { /* not a collaborator → none */ }
+
+            if (['admin', 'write', 'maintain'].includes(permission)) return; // authorized
+
+            // Unauthorized: strip the reserved label and explain.
+            await github.rest.issues.removeLabel({
+              owner: context.repo.owner, repo: context.repo.repo,
+              issue_number: context.payload.issue.number, name: label,
+            }).catch(() => {});
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner, repo: context.repo.repo,
+              issue_number: context.payload.issue.number,
+              body: `⚠️ \`${label}\` is a **trailhead-reserved** label and was removed automatically: only repo maintainers (write access) apply \`trailhead:*\` labels. It was applied by @${actor}, who lacks write access. If this issue should join the trailhead map, a maintainer will adopt it.`,
+            }).catch(() => {});

package/plugins/trailhead/hooks/lib/label-guard-sync.test.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-label-guard.yml and
+// templates/trailhead-label-guard-sync.js. Run: node label-guard-sync.test.js
+// No framework: plain asserts, mirrors the style of commit-msg-sync.test.js.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const templatesDir = path.resolve(__dirname, '..', '..', 'templates');
+const scriptPath = path.join(templatesDir, 'trailhead-label-guard-sync.js');
+const templatePath = path.join(templatesDir, 'trailhead-label-guard.yml');
+const oldFixturePath = path.join(__dirname, 'fixtures', 'label-guard-0.12.0.yml');
+const repoGuardPath = path.resolve(__dirname, '..', '..', '..', '..', '.github', 'workflows', 'trailhead-label-guard.yml');
+
+const {
+  isTrailheadGuard, jobGuardIf, hasJobLevelFilter, classify, syncLabelGuard, sessionNotice, ackGuard, parseArgs, GUARD_REL, ACK_REL,
+} = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const templateText = fs.readFileSync(templatePath, 'utf8');
+const oldText = fs.readFileSync(oldFixturePath, 'utf8');
+
+function mktmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-label-guard-sync-test-'));
+}
+function writeGuard(repoDir, text) {
+  const file = path.join(repoDir, GUARD_REL);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text);
+  return file;
+}
+
+// --- il template filtra a livello di job (i job saltati non sono fatturati) ---
+const cond = jobGuardIf(templateText);
+ok('template: jobs.guard has a job-level if', cond !== null);
+ok('template: job-level if filters on the trailhead: prefix',
+  cond.includes("startsWith(github.event.label.name, 'trailhead:')"));
+ok('template: job-level if skips the repository owner',
+  cond.includes('github.event.sender.login != github.repository_owner'));
+ok('template: job-level if skips allowlisted logins',
+  cond.includes("!contains(format(',{0},', vars.TRAILHEAD_LABEL_ALLOWLIST), format(',{0},', github.event.sender.login))"));
+ok('template: the job-level if sits before runs-on',
+  templateText.indexOf('    if: >-') < templateText.indexOf('    runs-on: ubuntu-latest'));
+ok('template: the in-script permission check is kept',
+  templateText.includes('getCollaboratorPermissionLevel') && templateText.includes("if (!label.startsWith('trailhead:')) return;"));
+ok("template: the repo's own guard is byte-identical to the template",
+  fs.readFileSync(repoGuardPath, 'utf8') === templateText);
+
+// --- riconoscimento e classificazione ----------------------------------------
+ok('isTrailheadGuard: template recognised', isTrailheadGuard(templateText));
+ok('isTrailheadGuard: 0.12.0 guard recognised', isTrailheadGuard(oldText));
+ok('isTrailheadGuard: foreign workflow rejected', !isTrailheadGuard('name: ci\non: push\n'));
+ok('jobGuardIf: 0.12.0 guard has no job-level if', jobGuardIf(oldText) === null);
+ok('jobGuardIf: a step-level if does not count',
+  jobGuardIf('jobs:\n  guard:\n    runs-on: x\n    steps:\n      - if: startsWith(github.event.label.name, \'trailhead:\')\n') === null);
+ok('jobGuardIf: an if on another job does not count',
+  jobGuardIf("jobs:\n  guard:\n    runs-on: x\n  other:\n    if: startsWith(github.event.label.name, 'trailhead:')\n") === null);
+ok('hasJobLevelFilter: single-line if accepted',
+  hasJobLevelFilter("jobs:\n  guard:\n    if: startsWith(github.event.label.name, 'trailhead:')\n    runs-on: x\n"));
+
+ok('classify: missing file -> absent', classify({ existingText: null, templateText }) === 'absent');
+ok('classify: template -> current', classify({ existingText: templateText, templateText }) === 'current');
+ok('classify: CRLF template -> current', classify({ existingText: templateText.replace(/\n/g, '\r\n'), templateText }) === 'current');
+ok('classify: 0.12.0 guard -> outdated', classify({ existingText: oldText, templateText }) === 'outdated');
+ok('classify: filtered but edited -> custom',
+  classify({ existingText: templateText + '# local tweak\n', templateText }) === 'custom');
+ok('classify: foreign workflow -> foreign', classify({ existingText: 'name: x\n', templateText }) === 'foreign');
+
+// --- syncLabelGuard: check-only non scrive, --apply migra --------------------
+{
+  const repo = mktmp();
+  const file = writeGuard(repo, oldText);
+  const r = syncLabelGuard({ repoDir: repo, templateText });
+  ok('sync check: outdated reported', r.status === 'outdated' && r.file === file);
+  ok('sync check: file untouched', fs.readFileSync(file, 'utf8') === oldText);
+  const a = syncLabelGuard({ repoDir: repo, templateText, apply: true });
+  ok('sync apply: outdated -> upgraded', a.status === 'upgraded');
+  ok('sync apply: file now equals the template', fs.readFileSync(file, 'utf8') === templateText);
+  ok('sync apply: no temp file left', fs.readdirSync(path.dirname(file)).length === 1);
+  ok('sync apply: second run -> current', syncLabelGuard({ repoDir: repo, templateText, apply: true }).status === 'current');
+}
+{
+  const repo = mktmp();
+  const a = syncLabelGuard({ repoDir: repo, templateText, apply: true });
+  ok('sync apply: absent -> installed', a.status === 'installed' && fs.readFileSync(a.file, 'utf8') === templateText);
+}
+for (const [label, text] of [['custom', templateText + '# local\n'], ['foreign', 'name: x\n']]) {
+  const repo = mktmp();
+  const file = writeGuard(repo, text);
+  const a = syncLabelGuard({ repoDir: repo, templateText, apply: true });
+  ok(`sync apply: ${label} left untouched`, a.status === label && fs.readFileSync(file, 'utf8') === text);
+}
+
+// --- offerta di sessione + ack ----------------------------------------------
+{
+  const repo = mktmp();
+  const file = writeGuard(repo, oldText);
+  const notice = sessionNotice({ repoDir: repo, templateText, scriptPath: scriptPath });
+  ok('notice: outdated guard -> offer', notice !== null && notice.includes('--apply') && notice.includes('--ack') && notice.includes('job-level'));
+ok('notice: asks the agent to explain why (billed minutes) in the question', notice.includes('put the reason in the question') && notice.includes('at least one minute') && notice.includes('skipped runs are free'));
+  ok('notice: read-only (no ack written)', !fs.existsSync(path.join(repo, ACK_REL)));
+  ok('notice: still offered on the next session', sessionNotice({ repoDir: repo, templateText, scriptPath }) !== null);
+  ok('ack: records the answer', ackGuard({ repoDir: repo }) === true && fs.existsSync(path.join(repo, ACK_REL)));
+  ok('notice: acked guard -> null', sessionNotice({ repoDir: repo, templateText, scriptPath }) === null);
+  fs.writeFileSync(file, oldText + '# edited\n');
+  ok('notice: comes back when the guard file changes', sessionNotice({ repoDir: repo, templateText, scriptPath }) !== null);
+}
+for (const [label, text] of [['current', templateText], ['custom', templateText + '# x\n'], ['foreign', 'name: x\n']]) {
+  const repo = mktmp();
+  writeGuard(repo, text);
+  ok(`notice: ${label} guard -> null`, sessionNotice({ repoDir: repo, templateText, scriptPath }) === null);
+}
+ok('notice: no guard -> null', sessionNotice({ repoDir: mktmp(), templateText, scriptPath }) === null);
+ok('ack: no guard -> false', ackGuard({ repoDir: mktmp() }) === false);
+
+// --- CLI ---------------------------------------------------------------------
+ok('parseArgs: --repo needs a value', Boolean(parseArgs(['--repo']).error));
+ok('parseArgs: unknown flag rejected', Boolean(parseArgs(['--nope']).error));
+ok('parseArgs: --apply with --notice rejected', Boolean(parseArgs(['--notice', '--apply']).error));
+ok('parseArgs: --notice with --ack rejected', Boolean(parseArgs(['--notice', '--ack']).error));
+{
+  const repo = mktmp();
+  writeGuard(repo, oldText);
+  const out = JSON.parse(execFileSync('node', [scriptPath, '--repo', repo], { encoding: 'utf8' }));
+  ok('cli: outdated reported as JSON', out.status === 'outdated');
+  const applied = JSON.parse(execFileSync('node', [scriptPath, '--repo', repo, '--apply'], { encoding: 'utf8' }));
+  ok('cli: --apply upgrades', applied.status === 'upgraded');
+}
+{
+  const repo = mktmp();
+  writeGuard(repo, oldText);
+  ok('cli: --notice prints the offer', execFileSync('node', [scriptPath, '--repo', repo, '--notice'], { encoding: 'utf8' }).includes('outdated'));
+  execFileSync('node', [scriptPath, '--repo', repo, '--ack']);
+  ok('cli: --notice silent after --ack', execFileSync('node', [scriptPath, '--repo', repo, '--notice'], { encoding: 'utf8' }) === '');
+}
+// L'hook SessionStart porta l'offerta nel contesto della sessione.
+{
+  const repo = mktmp();
+  execFileSync('git', ['init', '-q', repo]);
+  writeGuard(repo, oldText);
+  const hookPath = path.resolve(__dirname, '..', 'trailhead-check-update.js');
+  const run = () => execFileSync('node', [hookPath], {
+    input: JSON.stringify({ cwd: repo }), encoding: 'utf8',
+    env: { ...process.env, XDG_CACHE_HOME: path.join(repo, '.cache'), CLAUDE_CONFIG_DIR: path.join(repo, '.cfg') },
+  });
+  const ctx = (s) => (s ? JSON.parse(s).hookSpecificOutput.additionalContext : '');
+  ok('hook: SessionStart surfaces the label guard offer', ctx(run()).includes('label guard in this repo'));
+  ackGuard({ repoDir: repo });
+  ok('hook: no offer once acked', !ctx(run()).includes('label guard in this repo'));
+}
+
+console.log(`label-guard-sync: ${passed} passed`);

package/plugins/trailhead/hooks/lib/mockup-link.js

@@ -0,0 +1,50 @@
+// mockup-link.js: shared detection for the mockup-link guards.
+// Consumers: trailhead-mockup-link-guard.js (Claude Code, PreToolUse on
+// AskUserQuestion) and trailhead-mockup-link-stop.js (Codex, Stop on the
+// final reply, where an ask is a plain-text numbered list, not a tool call).
+// Pure functions, no dependencies.
+
+const MOCKUP_WORD = /mock-?ups?|prototip|prototype|wireframe/i;
+// The ask itself, second person (IT + EN): "approvi", "do you approve",
+// "accetti", "quale variante". Kept narrow on purpose: "il mockup approvato"
+// (a past approval) and the "want mockups first?" offer are not asks.
+const APPROVAL_WORD = /\bapprovi\b|\bapprove\b|\baccetti\b|\bquale variante\b|\bwhich variant\b/i;
+
+const URL_RE = /https?:\/\/\S+/i;
+const FILE_RE = /[\w~.\-/]+\.(?:html?|png|jpe?g|svg|webp|gif|pdf)\b/i;
+
+function hasLink(prose) {
+  return typeof prose === 'string' && (URL_RE.test(prose) || FILE_RE.test(prose));
+}
+
+// One question's question, header and option labels. Option descriptions are
+// left out: an offer like "Prima un mockup — attendo approvazione" describes
+// a future approval, it does not ask for one.
+function questionText(q) {
+  const labels = Array.isArray(q.options) ? q.options.map((o) => o && o.label) : [];
+  return [q.question, q.header, ...labels].filter((s) => typeof s === 'string').join('\n');
+}
+
+// AskUserQuestion input: does any single question ask to approve a mockup?
+function isMockupApprovalAsk(input) {
+  const qs = (input && Array.isArray(input.questions)) ? input.questions : [];
+  return qs.some((q) => {
+    const t = q ? questionText(q) : '';
+    return MOCKUP_WORD.test(t) && APPROVAL_WORD.test(t);
+  });
+}
+
+// A plain-text reply (Codex): it talks about a mockup and one of its
+// question lines (a line holding "?") asks for the approval.
+function isMockupApprovalMessage(text) {
+  if (typeof text !== 'string' || !MOCKUP_WORD.test(text)) return false;
+  return text.split('\n').some((l) => l.includes('?') && APPROVAL_WORD.test(l));
+}
+
+const BLOCK_REASON =
+  'trailhead mockup-link: this asks to approve/react to a mockup, but the message carries ' +
+  'no link to it. Write each mockup\'s clickable link (URL or file path, one line per ' +
+  'screen/variant) in the plain prose immediately before the question, not the project ' +
+  'name, then ask again. See "Surface the mockup" in _shared/techniques/prototype.md.';
+
+module.exports = { hasLink, isMockupApprovalAsk, isMockupApprovalMessage, BLOCK_REASON };

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

@@ -215,6 +215,20 @@ ok('reviewOffer: no ack, no stale pins -> null',
   ok('CLI with an unknown subcommand still exits 0', status === 0);
 }
 
+// --- helper test-only: compatibilita' del `since` con la versione ------------
+// Vero se base e' esattamente il prossimo bump patch, minor o major di current.
+function isNextBump(current, since) {
+  const [a, b, c] = current.split('.').map(Number);
+  return [`${a}.${b}.${c + 1}`, `${a}.${b + 1}.0`, `${a + 1}.0.0`].includes(since);
+}
+function sinceCompatible(since, version) {
+  return since === version || semverLt(since, version) || isNextBump(version, since);
+}
+ok('isNextBump accepts the next patch, minor and major of 0.11.1',
+  ['0.11.2', '0.12.0', '1.0.0'].every((v) => isNextBump('0.11.1', v)));
+ok('isNextBump rejects skipped bumps of 0.11.1',
+  ['0.13.0', '1.12.0', '0.11.3', '0.12.1'].every((v) => !isNextBump('0.11.1', v)));
+
 // --- shipped data invariants ---------------------------------------------
 {
   const pkg = JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', '..', '..', '..', 'package.json'), 'utf8'));
@@ -227,11 +241,13 @@ ok('reviewOffer: no ack, no stale pins -> null',
   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));
+  // Il `since` dell'ultima entry puo' anticipare la release: uguale, piu' vecchio
+  // o esattamente il prossimo bump patch/minor/major della versione corrente.
+  ok('shipped data: last since matches or precedes package.json version (or is its next bump)',
+    sinceCompatible(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));
+  ok('shipped data: last since matches or precedes plugin.json version (or is its next bump)',
+    sinceCompatible(cur.since, plugin.version));
 }
 
 {
@@ -241,6 +257,42 @@ ok('reviewOffer: no ack, no stale pins -> null',
     refDoc.includes(cur.claude.strong));
   ok('drift guard: current claude standard id appears in the Tier-class -> id section',
     refDoc.includes(cur.claude.standard));
+  ok('drift guard: current claude fast id appears in the Tier-class -> id section',
+    refDoc.includes(cur.claude.fast));
+}
+
+// --- default fast Haiku 5.5 dalla 0.12.0 -----------------------------------
+ok('current claude fast default is claude-haiku-5-5', cur.claude.fast === 'claude-haiku-5-5');
+ok('current opus/sonnet and codex tiers are unchanged',
+  cur.claude.strong === 'claude-opus-5-5' && cur.claude.standard === 'claude-sonnet-5-5' &&
+  cur.codex.strong === 'gpt-5.6-sol' && cur.codex.standard === 'gpt-5.6-terra' && cur.codex.fast === 'gpt-5.6-luna');
+
+for (const old of ['claude-haiku-4-5-20251001', 'claude-haiku-4-5']) {
+  const stale = stalePins({ models: { 'codebase-map': old } }, data);
+  ok(`stale haiku pin ${old} detected`, stale.length === 1 &&
+    stale[0].key === 'models.codebase-map' && stale[0].from === old && stale[0].to === 'claude-haiku-5-5');
+}
+ok('claude-haiku-5-5 itself is not stale',
+  stalePins({ models: { 'codebase-map': 'claude-haiku-5-5' } }, data).length === 0);
+
+{
+  const config = { models: { 'codebase-map': 'claude-haiku-4-5-20251001' } };
+  const offer = reviewOffer({ config, data, ack: '0.11.0' });
+  ok('reviewOffer: ack 0.11.0 with a Haiku 4.5 pin -> offer naming 0.12.0 and the line',
+    offer !== null && offer.notice.includes('0.12.0') &&
+    offer.notice.includes('models.codebase-map: claude-haiku-4-5-20251001 -> claude-haiku-5-5'));
+  ok('reviewOffer: ack 0.12.0 with a Haiku 4.5 pin -> null', reviewOffer({ config, data, ack: '0.12.0' }) === null);
+}
+
+{
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-mdr-haiku-'));
+  fs.mkdirSync(path.join(tmp, '.trailhead'));
+  const cfgPath = path.join(tmp, '.trailhead', 'config.json');
+  fs.writeFileSync(cfgPath, JSON.stringify({ models: { 'codebase-map': 'claude-haiku-4-5-20251001' } }));
+  const notice = check(tmp);
+  ok('check(): a Haiku 4.5 project pin is listed with its project-config source',
+    typeof notice === 'string' && notice.includes(
+      `models.codebase-map: claude-haiku-4-5-20251001 -> claude-haiku-5-5 (new default; from the project config, ${cfgPath})`));
 }
 
 // --- effectiveModels (pure merge, no mutation) --------------------------------

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

@@ -7,6 +7,10 @@
     { "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"] } } }
+      "supersedes": { "claude": { "strong": ["claude-opus-5"], "standard": ["claude-sonnet-4-8"] } } },
+    { "since": "0.12.0",
+      "claude": { "strong": "claude-opus-5-5", "standard": "claude-sonnet-5-5", "fast": "claude-haiku-5-5" },
+      "codex":  { "strong": "gpt-5.6-sol", "standard": "gpt-5.6-terra", "fast": "gpt-5.6-luna" },
+      "supersedes": { "claude": { "fast": ["claude-haiku-4-5-20251001", "claude-haiku-4-5"] } } }
   ]
 }

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

@@ -163,6 +163,29 @@ function reviewNotice(cwd) {
   }
 }
 
+// Offerta di upgrade del label guard del repo (stesso schema della review dei
+// modelli): solo quando il guard committato è la versione senza `if:` a
+// livello di job e l'utente non ha già risposto per quel file. Lo script di
+// sync vive in templates/: ../templates per plugin, dev e Codex, la copia npm
+// sotto <configDir>/trailhead/templates. Sola lettura; ogni errore -> null.
+function labelGuardNotice(cwd) {
+  try {
+    const candidates = [
+      path.join(__dirname, '..', 'templates'),
+      path.join(configDir(), 'trailhead', 'templates'),
+    ];
+    const dir = candidates.find((d) => fs.existsSync(path.join(d, 'trailhead-label-guard-sync.js')));
+    if (!dir) return null;
+    const repoDir = run('git', ['-C', cwd, 'rev-parse', '--show-toplevel']);
+    if (!repoDir) return null;
+    const scriptPath = path.join(dir, 'trailhead-label-guard-sync.js');
+    const templateText = fs.readFileSync(path.join(dir, 'trailhead-label-guard.yml'), 'utf8');
+    return require(scriptPath).sessionNotice({ repoDir, templateText, scriptPath }) || 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 {}.
@@ -190,9 +213,10 @@ function main(input) {
   const cwd = (input && typeof input.cwd === 'string' && input.cwd) || process.cwd();
 
   const review = reviewNotice(cwd);
+  const guard = labelGuardNotice(cwd);
   const update = updateNotice();
 
-  const parts = [review, update].filter(Boolean);
+  const parts = [review, guard, update].filter(Boolean);
   if (!parts.length) return;
 
   process.stdout.write(JSON.stringify({

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// trailhead-mockup-link-guard.js: PreToolUse(AskUserQuestion) hook.
+// Structural backstop for the Prototype technique's "surface the mockup" rule
+// (_shared/techniques/prototype.md): a message that asks to approve, react to,
+// or pick between mockups must carry each mockup's clickable link in its
+// plain prose, right before the question. The prose rule alone was skipped in
+// practice (an approval asked with only the project's name, no URL), so this
+// hook blocks an AskUserQuestion that is a mockup-approval ask when the
+// assistant prose immediately before it (no tool call in between) holds no
+// URL or file path.
+// Blocks with exit 2 + {"decision":"block",...}; allows everything else.
+// Fail-OPEN on any error (exit 0): a missing/unreadable transcript or an
+// unexpected shape must never wedge the workflow.
+// Claude-Code-specific (Codex has no AskUserQuestion tool; its twin there is
+// trailhead-mockup-link-stop.js). Detection lives in lib/mockup-link.js.
+// Pure functions are exported for tests; runs as a hook when executed directly.
+
+const fs = require('fs');
+const { hasLink, isMockupApprovalAsk, BLOCK_REASON } = require('./lib/mockup-link.js');
+
+// Only the transcript tail matters: the prose sits right before the ask.
+const TAIL_BYTES = 512 * 1024;
+
+const blocksOf = (e) => (Array.isArray(e.message && e.message.content) ? e.message.content : []);
+const isPendingAsk = (e) => e.type === 'assistant'
+  && blocksOf(e).some((b) => b.type === 'tool_use' && b.name === 'AskUserQuestion');
+
+// The assistant prose right before the ask: walk the main-chain entries back
+// from the end, skip the pending AskUserQuestion entries, and collect text
+// blocks until anything else (a user turn, a tool result, another tool call).
+function proseBeforeAsk(entries) {
+  const main = entries.filter((e) => e && (e.type === 'assistant' || e.type === 'user') && !e.isSidechain);
+  let i = main.length - 1;
+  while (i >= 0 && isPendingAsk(main[i])) i--;
+  const texts = [];
+  for (; i >= 0; i--) {
+    const e = main[i];
+    if (e.type !== 'assistant') break;
+    const blocks = blocksOf(e);
+    if (blocks.some((b) => b.type === 'tool_use')) break;
+    blocks.filter((b) => b.type === 'text').forEach((b) => texts.unshift(b.text || ''));
+  }
+  return texts.join('\n');
+}
+
+function readTail(file) {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const len = Math.min(size, TAIL_BYTES);
+    const buf = Buffer.alloc(len);
+    fs.readSync(fd, buf, 0, len, size - len);
+    return buf.toString('utf8');
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+// Parse JSONL leniently: the first line of a tail read may be cut mid-record.
+function parseEntries(text) {
+  return text.split('\n').flatMap((l) => {
+    try { return l.trim() ? [JSON.parse(l)] : []; } catch { return []; }
+  });
+}
+
+function block() {
+  process.stdout.write(JSON.stringify({ decision: 'block', code: 'MOCKUP_LINK_MISSING', reason: BLOCK_REASON }));
+  process.exit(2);
+}
+
+function run(data) {
+  try {
+    const payload = JSON.parse(data);
+    if (payload.tool_name && payload.tool_name !== 'AskUserQuestion') process.exit(0);
+    if (!isMockupApprovalAsk(payload.tool_input)) process.exit(0);
+    if (!payload.transcript_path) process.exit(0);
+    const prose = proseBeforeAsk(parseEntries(readTail(payload.transcript_path)));
+    if (!hasLink(prose)) block();
+  } catch {
+    // fall through to allow: a guard must never wedge the workflow
+  }
+  process.exit(0);
+}
+
+if (require.main === module) {
+  let data = '';
+  const timer = setTimeout(() => process.exit(0), 5000); // stdin never ends -> give up
+  process.stdin.on('data', (c) => (data += c));
+  process.stdin.on('end', () => {
+    clearTimeout(timer);
+    run(data);
+  });
+}
+
+module.exports = { isMockupApprovalAsk, hasLink, proseBeforeAsk };

package/plugins/trailhead/hooks/trailhead-mockup-link-guard.test.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// Tests for trailhead-mockup-link-guard.js. Run: node trailhead-mockup-link-guard.test.js
+// No framework: plain asserts + child_process for the end-to-end hook behaviour.
+const assert = require('assert');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  isMockupApprovalAsk,
+  hasLink,
+  proseBeforeAsk,
+} = require('./trailhead-mockup-link-guard.js');
+
+const HOOK = path.join(__dirname, 'trailhead-mockup-link-guard.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Costruttori di righe transcript (stesso shape JSONL di Claude Code)
+const text = (t) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'text', text: t }] } });
+const thinking = () => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'thinking', thinking: '' }] } });
+const toolUse = (name, input = {}) => ({ type: 'assistant', isSidechain: false, message: { content: [{ type: 'tool_use', id: 'x', name, input }] } });
+const toolResult = (c) => ({ type: 'user', isSidechain: false, message: { content: [{ type: 'tool_result', tool_use_id: 'x', content: c }] } });
+const userPrompt = (c) => ({ type: 'user', isSidechain: false, message: { content: c } });
+
+const approvalInput = {
+  questions: [{
+    question: 'Approvi il mockup della pagina FAQ?',
+    header: 'Mockup',
+    multiSelect: false,
+    options: [{ label: 'Approvo', description: 'Procedi col codice UI' }, { label: 'Chiedo modifiche', description: '' }],
+  }],
+};
+
+// --- isMockupApprovalAsk ---
+ok('IT mockup approval ask is detected', isMockupApprovalAsk(approvalInput));
+ok('EN mockup approval ask is detected', isMockupApprovalAsk({
+  questions: [{ question: 'Do you approve the login mockup?', options: [{ label: 'Approve' }, { label: 'Request changes' }] }],
+}));
+ok('pick between prototype variants is detected', isMockupApprovalAsk({
+  questions: [{ question: 'Quale variante del prototipo scegli?', options: [{ label: 'Variante A' }, { label: 'Variante B' }] }],
+}));
+ok('"want mockups first?" offer is NOT an approval ask', !isMockupApprovalAsk({
+  questions: [{ question: 'Vuoi prima un mockup della schermata?', options: [{ label: 'Sì' }, { label: 'No' }] }],
+}));
+// Regressione da una sessione reale: l'offerta di un mockup cita una
+// approvazione futura solo nella descrizione dell'opzione
+ok('mockup offer whose option description mentions approval is NOT an approval ask', !isMockupApprovalAsk({
+  questions: [{
+    question: 'Vuoi cambiare qualcosa nello scope della pagina FAQ?',
+    header: 'Scope',
+    options: [
+      { label: 'Va bene così', description: 'Procedo con lo scope descritto' },
+      { label: 'Prima un mockup', description: 'Disegno la pagina su claude.ai/design e attendo approvazione prima di scriverla' },
+    ],
+  }],
+}));
+ok('mockup and approval words in different questions do not combine', !isMockupApprovalAsk({
+  questions: [
+    { question: 'Vuoi prima un mockup?', options: [{ label: 'Sì' }] },
+    { question: 'Approvi il piano?', options: [{ label: 'Sì' }] },
+  ],
+}));
+ok('unrelated ask is not detected', !isMockupApprovalAsk({
+  questions: [{ question: 'Approvi il piano?', options: [{ label: 'Sì' }, { label: 'No' }] }],
+}));
+ok('malformed input is not detected', !isMockupApprovalAsk({}) && !isMockupApprovalAsk(null));
+
+// --- hasLink ---
+ok('https URL counts as a link', hasLink('Ecco: https://claude.ai/design/p/abc?file=faq.html'));
+ok('absolute html path counts as a link', hasLink('Mockup in /home/u/app/mockups/faq.html'));
+ok('relative html path counts as a link', hasLink('apri `mockups/faq.html`'));
+ok('markdown link to a file counts', hasLink('[faq](mockups/faq.html)'));
+ok('project name alone is NOT a link', !hasLink('Il mockup della pagina FAQ è pronto su MyApp, gruppo Marketing.'));
+ok('empty prose has no link', !hasLink(''));
+
+// --- proseBeforeAsk ---
+const failing = [
+  userPrompt('lavora #12'),
+  toolUse('Bash'),
+  toolResult('ok'),
+  thinking(),
+  text('Il mockup della pagina FAQ è pronto su MyApp, con indice sezioni.'),
+  toolUse('AskUserQuestion', approvalInput),
+];
+ok('prose right before the ask is collected', /pronto su MyApp/.test(proseBeforeAsk(failing)));
+
+const linkBeforeTools = [
+  userPrompt('lavora #12'),
+  text('Mockup: https://claude.ai/design/p/abc'),
+  toolUse('Bash'),
+  toolResult('ok'),
+  text('Pronto.'),
+  toolUse('AskUserQuestion', approvalInput),
+];
+ok('a link before an intervening tool call does not count', !hasLink(proseBeforeAsk(linkBeforeTools)));
+
+const sidechain = [
+  text('Mockup FAQ pronto.'),
+  { ...text('https://example.com/side'), isSidechain: true },
+  toolUse('AskUserQuestion', approvalInput),
+];
+ok('sidechain text is ignored', !hasLink(proseBeforeAsk(sidechain)));
+
+const noAskYet = [userPrompt('x'), text('Ecco https://a.b/c')];
+ok('works when the pending tool_use is not yet in the transcript', hasLink(proseBeforeAsk(noAskYet)));
+
+// --- end-to-end ---
+function writeTranscript(entries) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'th-mlg-'));
+  const f = path.join(dir, 't.jsonl');
+  fs.writeFileSync(f, entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
+  return f;
+}
+function runHook(payload) {
+  try {
+    const out = execFileSync('node', [HOOK], { input: JSON.stringify(payload) });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString() };
+  }
+}
+
+const r1 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: writeTranscript(failing) });
+ok('approval ask without a link in the prose is blocked (exit 2)', r1.code === 2 && /MOCKUP_LINK_MISSING/.test(r1.out));
+
+const withLink = [...failing.slice(0, 4), text('Mockup: https://claude.ai/design/p/abc?file=faq.html'), failing[5]];
+const r2 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: writeTranscript(withLink) });
+ok('approval ask with a link in the prose is allowed', r2.code === 0 && r2.out.trim() === '');
+
+const r3 = runHook({ tool_name: 'AskUserQuestion', tool_input: approvalInput, transcript_path: '/nonexistent/t.jsonl' });
+ok('missing transcript fails open', r3.code === 0);
+
+const r4 = runHook({ tool_name: 'Bash', tool_input: { command: 'ls' }, transcript_path: writeTranscript(failing) });
+ok('other tools are ignored', r4.code === 0);
+
+const r5 = runHook({ tool_name: 'AskUserQuestion', tool_input: { questions: [{ question: 'Approvi il piano?', options: [] }] }, transcript_path: writeTranscript(failing) });
+ok('non-mockup ask is allowed', r5.code === 0);
+
+let r6;
+try { execFileSync('node', [HOOK], { input: 'not json' }); r6 = 0; } catch (e) { r6 = e.status; }
+ok('unparseable input fails open', r6 === 0);
+
+console.log(`trailhead-mockup-link-guard: ${passed} passed`);