@marcomigozzi/trailhead 0.11.1 → 0.12.0

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-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`);

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// trailhead-mockup-link-stop.js: Stop hook (Codex).
+// Codex twin of trailhead-mockup-link-guard.js. On Codex trailhead asks its
+// questions as a plain-text numbered list (request_user_input is Plan-Mode
+// only), so there is no tool call to gate: this hook reads the final reply
+// (`last_assistant_message`) instead. When the reply asks to approve a mockup
+// (or pick between mockup variants) and carries no URL or file path, it
+// answers {"decision":"block","reason":...}: on Stop, Codex does not reject
+// the turn but continues it, with the reason as the next prompt, so the agent
+// rewrites the ask with the link.
+// Never blocks a turn that was already continued (`stop_hook_active`), so it
+// cannot loop. Fail-OPEN on any error (exit 0, no output).
+
+const { hasLink, isMockupApprovalMessage, BLOCK_REASON } = require('./lib/mockup-link.js');
+
+function run(data) {
+  try {
+    const payload = JSON.parse(data);
+    if (payload.stop_hook_active) process.exit(0);
+    const msg = payload.last_assistant_message;
+    if (isMockupApprovalMessage(msg) && !hasLink(msg)) {
+      process.stdout.write(JSON.stringify({ decision: 'block', reason: BLOCK_REASON }));
+    }
+  } 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);
+  });
+}

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Tests for trailhead-mockup-link-stop.js (+ lib/mockup-link.js message detection).
+// Run: node trailhead-mockup-link-stop.test.js
+const assert = require('assert');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { isMockupApprovalMessage } = require('./lib/mockup-link.js');
+
+const HOOK = path.join(__dirname, 'trailhead-mockup-link-stop.js');
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+// Risposta Codex: la domanda è un elenco numerato in testo semplice
+const noLink = [
+  'Il mockup della pagina FAQ è pronto su MyApp, con indice sezioni.',
+  '',
+  'Approvi il mockup della pagina FAQ?',
+  '1. Approvo',
+  '2. Chiedo modifiche',
+].join('\n');
+const withLink = noLink.replace('pronto su MyApp', 'pronto: https://claude.ai/design/p/abc?file=faq.html');
+
+// --- isMockupApprovalMessage ---
+ok('IT approval reply is detected', isMockupApprovalMessage(noLink));
+ok('EN approval reply is detected', isMockupApprovalMessage('Mockup ready.\n\nDo you approve the login mockup?\n1. Yes\n2. No'));
+ok('variant pick is detected', isMockupApprovalMessage('Due prototipi pronti.\nQuale variante scegli?\n1. A\n2. B'));
+ok('past approval mention is NOT an ask', !isMockupApprovalMessage('Ho implementato il mockup approvato. Commit fatto.'));
+ok('approval word without a question line is NOT an ask', !isMockupApprovalMessage('Approvi il mockup quando vuoi.'));
+ok('"want mockups first?" offer is NOT an ask', !isMockupApprovalMessage('Vuoi prima un mockup?\n1. Sì\n2. No'));
+ok('non-string is not detected', !isMockupApprovalMessage(undefined));
+
+// --- end-to-end ---
+function runHook(payload) {
+  try {
+    const out = execFileSync('node', [HOOK], { input: typeof payload === 'string' ? payload : JSON.stringify(payload) });
+    return { code: 0, out: out.toString() };
+  } catch (e) {
+    return { code: e.status, out: (e.stdout || '').toString() };
+  }
+}
+const parse = (s) => { try { return JSON.parse(s); } catch { return null; } };
+
+const r1 = runHook({ hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: noLink });
+const j1 = parse(r1.out);
+ok('approval reply without a link: continues the turn with a block decision (exit 0, JSON)',
+  r1.code === 0 && j1 && j1.decision === 'block' && /mockup-link/.test(j1.reason));
+
+const r2 = runHook({ hook_event_name: 'Stop', stop_hook_active: false, last_assistant_message: withLink });
+ok('approval reply with a link is allowed', r2.code === 0 && r2.out.trim() === '');
+
+const r3 = runHook({ hook_event_name: 'Stop', stop_hook_active: true, last_assistant_message: noLink });
+ok('already-continued turn is never blocked again (no loop)', r3.code === 0 && r3.out.trim() === '');
+
+const r4 = runHook({ hook_event_name: 'Stop', stop_hook_active: false });
+ok('missing last_assistant_message fails open', r4.code === 0 && r4.out.trim() === '');
+
+const r5 = runHook({ hook_event_name: 'Stop', last_assistant_message: 'Fatto, commit pushato.' });
+ok('ordinary reply is allowed', r5.code === 0 && r5.out.trim() === '');
+
+const r6 = runHook('not json');
+ok('unparseable input fails open', r6.code === 0 && r6.out.trim() === '');
+
+console.log(`trailhead-mockup-link-stop: ${passed} passed`);