@marcomigozzi/trailhead 0.12.0 → 0.13.0

package/README.it.md

@@ -26,7 +26,7 @@ Due approcci al lavoro di progetto guidato dagli agenti risolvono ciascuno una m
 
 Lavorando su entrambi, uno schema continuava a ripresentarsi: **usa una mappa e un onboarding in stile Wayfinder per decidere la forma del lavoro, poi un motore in stile GSD per costruire ogni pezzo, senza mai lasciare l'issue tracker.** `trailhead` è quello schema trasformato in un'unica skill, una sua interpretazione autonoma di entrambe le idee anziché un wrapper attorno all'una o all'altra.
 
-> **trailhead è self-contained** nel senso che ha **zero dipendenze da plugin esterni**: gli agent di trailhead e i built-in dell'host vanno bene, e nessun'altra skill o plugin è richiesta. Wayfinder e GSD sono *ispirazione*, non dipendenze. Ogni tecnica che quei sistemi impacchettano come skill separata (grilling, TDD, debugging sistematico, codebase mapping, code review) è **integrata qui come protocollo inline**. Il core di trailhead non invoca nessun'altra skill; ogni tecnica del motore dispatcha al **proprio agent `trailhead-*`** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, più `trailhead-fix` e `trailhead-codebase-map`), scritto una volta come file `agents/trailhead-*.md` versionato e **proiettato su ogni host** (su Codex diventa `~/.codex/agents/trailhead-*.toml` generato dalla stessa sorgente). Questi agent sono **thin** (identità + tool policy + un modello guidato dalla config, con il protocollo della tecnica iniettato allo spawn) e girano sul toolkit di subagent nativo dell'host (il tool `Agent` integrato di Claude Code, oppure il toolkit `multi_agent` di Codex). L'unica cosa da installare è trailhead stesso. C'è un'unica eccezione opt-in: la modalità mockup hosted. Quando abilitata, `claude.ai/design` costruisce il mockup su claude.ai/design (solo Claude): per default una canvas (la skill integrata `/design` pubblicata come Artifact, o un progetto creato a mano nella web app, non guidato da MCP) o, per una libreria di componenti condivisa, un progetto design-system tramite DesignSync (l'MCP `claude-design` più la skill `/design-sync`, l'unica superficie guidata da MCP). Una terza modalità, `stitch`, usa l'MCP Google Stitch e funziona sia su **Claude Code sia su Codex**, quindi è l'opzione hosted cross-host. Se l'MCP della modalità configurata non è connesso, offre un'installazione una tantum e ripiega sui mockup su disco locale se rifiuti; su Codex, dove `claude.ai/design` non è disponibile, offre di passare a `stitch` prima di ripiegare sul disco locale.
+> **trailhead è self-contained** nel senso che ha **zero dipendenze da plugin esterni**: gli agent di trailhead e i built-in dell'host vanno bene, e nessun'altra skill o plugin è richiesta. Wayfinder e GSD sono *ispirazione*, non dipendenze. Ogni tecnica che quei sistemi impacchettano come skill separata (grilling, TDD, debugging sistematico, codebase mapping, code review) è **integrata qui come protocollo inline**. Il core di trailhead non invoca nessun'altra skill; ogni tecnica del motore dispatcha al **proprio agent `trailhead-*`** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, più `trailhead-fix` e `trailhead-codebase-map`), scritto una volta come file `agents/trailhead-*.md` versionato e **proiettato su ogni host** (su Codex diventa `~/.codex/agents/trailhead-*.toml` generato dalla stessa sorgente). Questi agent sono **thin** (identità + tool policy + un modello guidato dalla config, con il protocollo della tecnica iniettato allo spawn) e girano sul toolkit di subagent nativo dell'host (il tool `Agent` integrato di Claude Code, oppure il toolkit `multi_agent` di Codex). L'unica cosa da installare è trailhead stesso. C'è un'unica eccezione opt-in: la modalità mockup hosted. Quando abilitata, `artifacts` costruisce il mockup come canvas Design **Artifact** su claude.ai tramite il tool `Artifact` integrato in Claude Code (solo Claude Code, niente da installare), con il tuo design system installato sul canvas. Una seconda modalità hosted, `stitch`, usa l'MCP Google Stitch e funziona sia su **Claude Code sia su Codex**, quindi è l'opzione cross-host; se il suo MCP non è connesso, offre un'installazione una tantum e ripiega sui mockup su disco locale se rifiuti. Dove il tool `Artifact` non c'è (Codex, sessioni con API key), offre di passare a `stitch` prima di ripiegare sul disco locale.
 
 Le scelte di design che ne derivano:
 
@@ -70,7 +70,7 @@ npx @marcomigozzi/trailhead --dir=<path> # punta a una config dir specifica
 ```
 Su **Claude Code** copia la skill (+ le sue `references/`), i comandi `/trailhead:*`, gli hook (in `hooks/`, registrati in `settings.json`) incluso un **update check** al SessionStart, e i template di label-guard + statusline, in modo idempotente.
 
-Su **Codex CLI** (`--codex`) proietta una skill nativa Codex invocata come **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), una skill sottile **`$trailhead-<verb>`** per ogni verbo per la discoverability, le sei guardrail come **hook** nativi di Codex (`~/.codex/hooks.json`, abilitando `features.hooks`; la search guard è solo per Claude Code e non è proiettata su Codex), e i pin di modello per-tecnica da **`models.codex.*`** in `~/.codex/agents/`. Serve Codex **0.145.0+** (l'installer fa un gate su `codex --version`). La modalità mockup `claude.ai/design` non è disponibile su Codex; lì l'opzione hosted è la modalità cross-host `design: stitch` (MCP Google Stitch), con il disco locale come ripiego.
+Su **Codex CLI** (`--codex`) proietta una skill nativa Codex invocata come **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), una skill sottile **`$trailhead-<verb>`** per ogni verbo per la discoverability, le sei guardrail come **hook** nativi di Codex (`~/.codex/hooks.json`, abilitando `features.hooks`; la search guard è solo per Claude Code e non è proiettata su Codex), e i pin di modello per-tecnica da **`models.codex.*`** in `~/.codex/agents/`. Serve Codex **0.145.0+** (l'installer fa un gate su `codex --version`). La modalità mockup `artifacts` (il tool `Artifact` di Claude Code) non è disponibile su Codex; lì l'opzione hosted è la modalità cross-host `design: stitch` (MCP Google Stitch), con il disco locale come ripiego.
 
 Ri-esegui l'install per aggiornare, oppure esegui **`/trailhead:update`** (Claude) / **`$trailhead update`** (Codex) da dentro l'agente: rileva come trailhead è stato installato e installa la versione più recente dove è sicuro farlo (un `git pull` per un dev-symlink, una ri-esecuzione `npx` per npm, o `/plugin update` per il plugin). Quando esiste una versione più recente, la statusline mostra un flag `⬆ trailhead <version>` (Claude).
 
@@ -130,7 +130,7 @@ Frontier iniziale = ①③④, tre persone possono partire in parallelo. Poi:
 - **① research** → un subagent legge la documentazione, restituisce un finding pronto per la decisione, chiude → sblocca ②.
 - **② decision** → dirama le opzioni, grill per scegliere native vs custom, registra il perché.
 - **③ task** → l'agente ti consegna una checklist (servono i *tuoi* account Google/GitHub); tu registri le app, lui registra dove vivono le credenziali.
-- **④ prototype** → una schermata di login grezza (sul progetto claude.ai/design configurato), approvata prima del codice UI.
+- **④ prototype** → una schermata di login grezza (sul canvas Artifacts configurato), approvata prima del codice UI.
 - Con ②③④ chiusi, **⑤ build** si diploma → discuss → plan → execute (commit atomici, TDD ai seam dell'auth) → verify (test + code review + acceptance: chiesto chi guida, l'agente va AI-driven e guida il browser attraverso il vero flusso di login).
 - Dopo il rilascio noti un redirect sbagliato in prod → `/trailhead:bug --of ⑤ "GitHub redirect goes to localhost"` → un nuovo ticket che porta `Regression of: ⑤`, lavorato repro → diagnose → fix → verify. ⑤ resta chiuso.
 
@@ -229,7 +229,7 @@ Ogni tipo ha il proprio motore inline: nessuna skill esterna viene invocata.
 |---|---|---|---|
 | 🧭 `decision` | una scelta | HITL | diverge le opzioni se non chiare, poi grill per convergere su una |
 | 🔬 `research` | un fatto | AFK | un subagent su un branch usa-e-getta (l'unico tipo eseguito in parallelo) |
-| 🎨 `prototype` | una direzione approvata | HITL | un artefatto grezzo usa-e-getta a cui reagire; le schermate UI passano da qui (disco, o un progetto claude.ai/design configurato) prima del codice UI |
+| 🎨 `prototype` | una direzione approvata | HITL | un artefatto grezzo usa-e-getta a cui reagire; le schermate UI passano da qui (disco, un canvas Artifacts, o Stitch) prima del codice UI |
 | 🔨 `build` | codice funzionante | HITL/AFK | `discuss → plan → execute → verify`: commit atomici, TDD ai seam, **prima un mockup per la UI rivolta all'utente** (tecnica Prototype, gated da `design.approval`), code review + acceptance testing (chiede chi guida, AI o umano, poi browser-drive o UAT conversazionale passo-passo) |
 | 🐛 `bug` | codice corretto | HITL/AFK | `repro → diagnose → fix → verify`; un difetto in lavoro chiuso è un ticket *nuovo* (`Regression of:`), non una riapertura |
 | 🔧 `task` | un cambiamento di stato esterno | HITL/AFK | lavoro manuale che sblocca una decision (provisioning accessi, spostamento dati, iscrizioni) |
@@ -304,8 +304,9 @@ Il passo **📊 statusline** offre di installare la status bar di trailhead per
 |---|---|---|
 | `ticket.language` | un codice ISO 639-1 (**`en`**) | la lingua in cui trailhead **scrive** la sua prosa GitHub e le descrizioni dei commit, disaccoppiata dalla lingua in cui conversa |
 | `models.{plan,execute,research,review,debug,verify,codebase-map}` | un id modello completo **versionato** (**inherit session**) | quale modello esegue ogni attività; `plan` ed `execute` sono sempre impostati separatamente |
-| `design` | **`disk`** \| `claude.ai/design` \| `stitch` | dove vanno i mockup UI: HTML usa-e-getta locale, claude.ai/design via l'MCP ufficiale Claude Design di Anthropic, o Google Stitch (cross-host, via l'MCP Stitch) |
-| `design.surface` | **`canvas`** \| `design-system` | sotto `claude.ai/design` o `stitch`, quale superficie: un progetto canvas (default) o un progetto design-system via `/design-sync` |
+| `design` | **`disk`** \| `artifacts` \| `stitch` | dove vanno i mockup UI: HTML usa-e-getta locale, un canvas Design **Artifact** su claude.ai (solo Claude Code), o Google Stitch (cross-host, via l'MCP Stitch). Il vecchio valore `claude.ai/design` viene letto come `artifacts` |
+| `design.surface` | **`canvas`** \| `design-system` | solo `stitch`: un progetto Stitch di schermate (default) o un design system Stitch condiviso |
+| `design.system` | URL di un Design System Artifact | solo `artifacts`: il design system installato sul canvas dei mockup (chiesto alla prima schermata se non impostato) |
 | `design.approval` | **`explicit`** \| `auto` | attendi l'approvazione del mockup prima del codice UI, o procedi senza bloccare |
 | `tdd` | **`seams`** \| `on` \| `off` | come il motore `build` testa |
 | `acceptance.browser` | **`auto`** \| `on` \| `off` | guida il browser in Verify (dopo aver chiesto chi guida, AI o umano); `off` esegue comunque controlli AI-driven via comandi, e ti accompagna in una UAT conversazionale per ciò che solo tu puoi fare (passo-passo in chat, non una checklist da fare da solo) |
@@ -330,14 +331,13 @@ Esempio di file di config (la stessa forma funziona per il `.trailhead/config.js
 { "ticket": { "language": "en" }, "models": { "plan": "claude-opus-5-5", "execute": "claude-sonnet-5-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }
 ```
 
-**Design mockups.** `design: disk` (il default) deposita un mockup HTML statico usa-e-getta accanto al codice e lo collega dal ticket. `design: claude.ai/design` invece costruisce il mockup su claude.ai/design (canvas tramite la skill integrata `/design` o un progetto creato a mano nella web app; design-system tramite l'**MCP ufficiale Claude Design** di Anthropic, `claude mcp add --scope user --transport http claude-design https://api.anthropic.com/v1/design/mcp`, accedi con `/design-login`), dove lo affini visivamente, e `design: stitch` usa l'**MCP Google Stitch** (`claude mcp add --scope user --transport http stitch https://stitch.googleapis.com/mcp`), il generatore UI di Google basato su Gemini che gira sia su **Claude Code sia su Codex** (l'opzione hosted cross-host). Entrambe onorano `design.surface`:
+**Design mockups.** `design: disk` (il default) deposita un mockup HTML statico usa-e-getta accanto al codice e lo collega dal ticket. `design: artifacts` costruisce il mockup come **canvas Design Artifact** su claude.ai, tramite il tool `Artifact` integrato in Claude Code (niente da installare), dove lo affini visivamente, lo commenti e lo esporti; `design: stitch` usa l'**MCP Google Stitch** (`claude mcp add --scope user --transport http stitch https://stitch.googleapis.com/mcp`), il generatore UI di Google basato su Gemini che gira sia su **Claude Code sia su Codex** (l'opzione hosted cross-host).
 
-- **`canvas`** (default): una schermata singola a cui reagire, modificabile ed esportabile come prototipo live. Sotto `claude.ai/design` è la skill integrata `/design` (pubblicata come Artifact) o un progetto claude.ai/design creato a mano nella web app; sotto `stitch` è un progetto Stitch.
-- **`design-system`**: un progetto design-system guidato da **DesignSync** (la skill `/design-sync` più l'MCP `claude-design`), per una libreria di componenti condivisa tenuta in sync.
+Con **`artifacts`**, alla prima schermata UI trailhead aggancia un canvas: **sceglierne uno esistente**, **incollare un URL**, oppure **crearne uno nuovo** (ti chiede il nome), e ne mette in cache l'URL in `design.project`. Ogni schermata (e ogni variante) è una propria tavola, raggruppata in una pagina del canvas per ticket; il design system in `design.system` (quello predefinito del tuo account, o quello che scegli) viene installato sul canvas, così colori, tipografia e componenti sono a portata di mano. I messaggi di approvazione riportano l'URL del canvas più il nome di ogni tavola. Una volta che approvi, trailhead **rilegge** le tavole (nel caso tu le abbia modificate live) prima di scrivere qualsiasi codice UI.
 
-Alla prima schermata UI, trailhead si aggancia a una superficie: per un progetto **Stitch** o un **design-system claude.ai/design** può **sceglierne uno esistente**, **incollare un URL**, oppure **crearne uno nuovo** (ti chiede il nome); per una **canvas claude.ai/design** non esiste la creazione via MCP, quindi usa la skill `/design` (un **Artifact**) o un progetto web-app di cui incolli l'URL `/p/<id>`. Fa il caching dell'id/URL scelto in `design.project`; un progetto già in cache da prima mantiene la superficie `design-system` a meno che tu non imposti `design.surface`, così i setup esistenti non cambiano. Ogni schermata viene aggiunta lì, e la sua URL è collegata dal ticket. Una volta che approvi, trailhead **ri-fetcha** il design corrente (nel caso tu l'abbia modificato live) prima di scrivere qualsiasi codice UI.
+Con **`stitch`**, `design.surface` sceglie un progetto Stitch di schermate (`canvas`, default) o un design system Stitch condiviso (`design-system`); trailhead lo sceglie, incolla o crea allo stesso modo, e offre una volta di installare l'MCP Stitch se non è connesso (se rifiuti, ripiega sul disco locale).
 
-Se l'MCP della modalità hosted non è connesso, trailhead **offre di installarlo una volta** (`claude mcp add ...`); se rifiuti, ripiega sul disco locale. (La superficie **canvas** di `claude.ai/design` non richiede MCP, quindi per lei non viene offerto nulla; solo la superficie **design-system** ha l'offerta di installazione.) Su Codex `claude.ai/design` non è disponibile, quindi trailhead offre di passare a `stitch` (cross-host) prima di ripiegare sul disco locale. `design.approval` decide se il build attende il tuo esplicito via libera (`explicit`), o procede subito dopo aver mostrato il mockup (`auto`); non tocca l'offerta di installazione una tantum, che compare in entrambi i casi.
+**Passare da claude.ai/design.** Il sito standalone di Claude Design chiude il 14/12/2026 e i suoi design ora vivono in Claude come Artifacts. Una config che dice ancora `design: claude.ai/design` continua a funzionare come `artifacts` (trailhead te lo dice una volta e offre di riscrivere la chiave), ma un progetto claude.ai/design in cache non è riutilizzabile: migra i design system dal banner della pagina Artifacts e lascia che trailhead agganci un nuovo canvas. Dove il tool `Artifact` non c'è (Codex, o una sessione con API key), trailhead offre di passare a `stitch` prima di ripiegare sul disco locale. `design.approval` decide se il build attende il tuo esplicito via libera (`explicit`), o procede subito dopo aver mostrato il mockup (`auto`).
 
 ---
 

package/README.md

@@ -26,7 +26,7 @@ Two approaches to agent-driven project work each nail one half of the problem:
 
 Working across both, one pattern kept recurring: **use a Wayfinder-style map and onboarding to decide the shape of the work, then a GSD-style engine to build each piece, without ever leaving the issue tracker.** `trailhead` is that pattern made into a set of cohesion-clustered skills over a shared core, its own self-contained take on both ideas rather than a wrapper around either.
 
-> **trailhead is self-contained** in the sense that it has **zero external-plugin dependencies**: trailhead-owned agents and the host's built-ins are fine, and no other skill or plugin is required. Wayfinder and GSD are *inspiration*, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is **built in here as an inline protocol**. trailhead's core invokes no other skill; each engine technique dispatches to **trailhead's own `trailhead-*` agent** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, plus `trailhead-fix` and `trailhead-codebase-map`), authored once as a committed `agents/trailhead-*.md` file and **projected to each host** (Codex gets `~/.codex/agents/trailhead-*.toml` generated from that same source). These agents are **thin** (identity + tool policy + a config-driven model, with the technique protocol injected at spawn) and run on the host's native subagent toolkit (Claude Code's built-in `Agent` tool, or Codex's `multi_agent` toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockup mode. When enabled, `claude.ai/design` builds the mockup on claude.ai/design (Claude only): by default a canvas (the built-in `/design` skill published as an Artifact, or a hand-made web-app project, not MCP-driven) or, for a shared component library, a design-system project via DesignSync (the `claude-design` MCP plus the `/design-sync` skill, the only MCP-driven surface). A third mode, `stitch`, uses the Google Stitch MCP and works on **both Claude Code and Codex**, so it's the cross-host hosted option. If a hosted mode's MCP isn't connected, it offers a one-time install and falls back to local-disk mockups if you decline; on Codex, where `claude.ai/design` isn't available, it offers to switch to `stitch` before falling to local disk.
+> **trailhead is self-contained** in the sense that it has **zero external-plugin dependencies**: trailhead-owned agents and the host's built-ins are fine, and no other skill or plugin is required. Wayfinder and GSD are *inspiration*, not dependencies. Every technique those systems package as a separate skill (grilling, TDD, systematic debugging, codebase mapping, code review) is **built in here as an inline protocol**. trailhead's core invokes no other skill; each engine technique dispatches to **trailhead's own `trailhead-*` agent** (`trailhead-executor`, `trailhead-plan`, `trailhead-research`, `trailhead-code-review`, `trailhead-debug`, plus `trailhead-fix` and `trailhead-codebase-map`), authored once as a committed `agents/trailhead-*.md` file and **projected to each host** (Codex gets `~/.codex/agents/trailhead-*.toml` generated from that same source). These agents are **thin** (identity + tool policy + a config-driven model, with the technique protocol injected at spawn) and run on the host's native subagent toolkit (Claude Code's built-in `Agent` tool, or Codex's `multi_agent` toolkit). The only thing to install is trailhead itself. There is one opt-in exception: hosted mockup mode. When enabled, `artifacts` builds the mockup as a Design canvas **Artifact** on claude.ai through Claude Code's built-in `Artifact` tool (Claude Code only, nothing to install), with your design system installed on the canvas. A second hosted mode, `stitch`, uses the Google Stitch MCP and works on **both Claude Code and Codex**, so it's the cross-host option; if its MCP isn't connected, it offers a one-time install and falls back to local-disk mockups if you decline. Where the `Artifact` tool isn't available (Codex, API-key sessions), it offers to switch to `stitch` before falling to local disk.
 
 The design choices that fall out of it:
 
@@ -70,7 +70,7 @@ npx @marcomigozzi/trailhead --dir=<path> # target a specific config dir
 ```
 On **Claude Code** it copies the skill (+ its `references/`), the `/trailhead:*` commands, the hooks (into `hooks/`, registered in `settings.json`) including a SessionStart **update check**, and the label-guard + statusline templates, idempotently.
 
-On **Codex CLI** (`--codex`) it projects a native Codex skill invoked as **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), one thin **`$trailhead-<verb>`** skill per verb for discoverability, the six guardrails as native Codex **hooks** (`~/.codex/hooks.json`, enabling `features.hooks`; the search guard is Claude-Code-only and isn't projected to Codex), and per-technique subagent model pins from **`models.codex.*`** into `~/.codex/agents/`. Codex **0.145.0+** is required (the installer gates on `codex --version`). The `claude.ai/design` mockup mode isn't available on Codex; the cross-host `design: stitch` mode (Google Stitch MCP) is the hosted option there, with local disk as the fallback.
+On **Codex CLI** (`--codex`) it projects a native Codex skill invoked as **`$trailhead`** (`$trailhead work`, `$trailhead new "idea"`, …), one thin **`$trailhead-<verb>`** skill per verb for discoverability, the six guardrails as native Codex **hooks** (`~/.codex/hooks.json`, enabling `features.hooks`; the search guard is Claude-Code-only and isn't projected to Codex), and per-technique subagent model pins from **`models.codex.*`** into `~/.codex/agents/`. Codex **0.145.0+** is required (the installer gates on `codex --version`). The `artifacts` mockup mode (Claude Code's `Artifact` tool) isn't available on Codex; the cross-host `design: stitch` mode (Google Stitch MCP) is the hosted option there, with local disk as the fallback.
 
 Re-run the install to update, or run **`/trailhead:update`** (Claude) / **`$trailhead update`** (Codex) from inside the agent: it detects how trailhead was installed and installs the newer version where that is safe (a `git pull` for a dev-symlink, an `npx` re-run for npm, or `/plugin update` for the plugin). When a newer version exists, the statusline shows a `⬆ trailhead <version>` flag (Claude).
 
@@ -130,7 +130,7 @@ Initial frontier = ①③④, three people can start in parallel. Then:
 - **① research** → a subagent reads the docs, returns a decision-ready finding, closes → unblocks ②.
 - **② decision** → diverge the options, grill to choose native vs custom, record the why.
 - **③ task** → the agent hands you a checklist (it needs *your* Google/GitHub accounts); you register the apps, it records where the credentials live.
-- **④ prototype** → a rough login screen (on the configured claude.ai/design project), approved before UI code.
+- **④ prototype** → a rough login screen (on the configured Artifacts canvas), approved before UI code.
 - With ②③④ closed, **⑤ build** graduates → discuss → plan → execute (atomic commits, TDD at the auth seams) → verify (tests + code review + acceptance: asked who drives, the agent goes AI-driven and drives the browser through the real login flow).
 - After it ships you spot a wrong redirect in prod → `/trailhead:bug --of ⑤ "GitHub redirect goes to localhost"` → a new ticket carrying `Regression of: ⑤`, worked repro → diagnose → fix → verify. ⑤ stays closed.
 
@@ -229,7 +229,7 @@ Each type has its own inline engine: no external skill is invoked.
 |---|---|---|---|
 | 🧭 `decision` | a choice | HITL | diverge the options if unclear, then grill to converge on one |
 | 🔬 `research` | a fact | AFK | a subagent on a throwaway branch (the only type run in parallel) |
-| 🎨 `prototype` | an approved direction | HITL | a rough throwaway artifact to react to; UI screens go through this (disk, or a configured claude.ai/design project) before UI code |
+| 🎨 `prototype` | an approved direction | HITL | a rough throwaway artifact to react to; UI screens go through this (disk, an Artifacts canvas, or Stitch) before UI code |
 | 🔨 `build` | working code | HITL/AFK | `discuss → plan → execute → verify`: atomic commits, TDD at seams, **a mockup first for user-facing UI** (Prototype technique, gated by `design.approval`), code review + acceptance testing (asks who drives, AI or human, then browser-drive or conversational step-by-step UAT) |
 | 🐛 `bug` | corrected code | HITL/AFK | `repro → diagnose → fix → verify`; a defect in closed work is a *new* ticket (`Regression of:`), not a reopen |
 | 🔧 `task` | an external state change | HITL/AFK | manual work that unblocks a decision (provision access, move data, sign up) |
@@ -304,8 +304,9 @@ The **📊 statusline** step offers to install trailhead's Claude Code status ba
 |---|---|---|
 | `ticket.language` | an ISO 639-1 code (**`en`**) | the language trailhead **writes** its GitHub prose & commit descriptions in, decoupled from the language it converses in |
 | `models.{plan,execute,research,review,debug,verify,codebase-map}` | a full **versioned** model id (**inherit session**) | which model runs each activity; `plan` and `execute` are always set separately |
-| `design` | **`disk`** \| `claude.ai/design` \| `stitch` | where UI mockups go: local throwaway HTML, claude.ai/design via Anthropic's official Claude Design MCP, or Google Stitch (cross-host, via the Stitch MCP) |
-| `design.surface` | **`canvas`** \| `design-system` | under `claude.ai/design` or `stitch`, which surface: a canvas project (default) or a design-system project via `/design-sync` |
+| `design` | **`disk`** \| `artifacts` \| `stitch` | where UI mockups go: local throwaway HTML, a Design canvas **Artifact** on claude.ai (Claude Code only), or Google Stitch (cross-host, via the Stitch MCP). The legacy `claude.ai/design` value is read as `artifacts` |
+| `design.surface` | **`canvas`** \| `design-system` | `stitch` only: a Stitch project of screens (default) or a shared Stitch design system |
+| `design.system` | Design System Artifact URL | `artifacts` only: the design system installed on the mockup canvas (asked at the first screen if unset) |
 | `design.approval` | **`explicit`** \| `auto` | wait for mockup approval before UI code, or proceed without blocking |
 | `tdd` | **`seams`** \| `on` \| `off` | how the `build` engine tests |
 | `acceptance.browser` | **`auto`** \| `on` \| `off` | drive the browser in Verify (after asking who drives, AI or human); `off` still runs AI-driven checks via commands, and walks you through a conversational UAT for anything only you can do (step by step in chat, not a checklist to self-serve) |
@@ -330,14 +331,13 @@ Example config file (the same shape works for the project `.trailhead/config.jso
 { "ticket": { "language": "en" }, "models": { "plan": "claude-opus-5-5", "execute": "claude-sonnet-5-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }
 ```
 
-**Design mockups.** `design: disk` (the default) drops a throwaway static HTML mockup next to the code and links it from the ticket. `design: claude.ai/design` instead builds the mockup on claude.ai/design (canvas via the built-in `/design` skill or a hand-made web-app project; design-system via Anthropic's **official Claude Design MCP**, `claude mcp add --scope user --transport http claude-design https://api.anthropic.com/v1/design/mcp`, sign in with `/design-login`), where you refine it visually, and `design: stitch` uses the **Google Stitch MCP** (`claude mcp add --scope user --transport http stitch https://stitch.googleapis.com/mcp`), Google's Gemini-powered UI generator that runs on **both Claude Code and Codex** (the cross-host hosted option). Both honour `design.surface`:
+**Design mockups.** `design: disk` (the default) drops a throwaway static HTML mockup next to the code and links it from the ticket. `design: artifacts` builds the mockup as a **Design canvas Artifact** on claude.ai, through Claude Code's built-in `Artifact` tool (nothing to install), where you refine it visually, comment on it and export it; `design: stitch` uses the **Google Stitch MCP** (`claude mcp add --scope user --transport http stitch https://stitch.googleapis.com/mcp`), Google's Gemini-powered UI generator that runs on **both Claude Code and Codex** (the cross-host hosted option).
 
-- **`canvas`** (default): a one-off screen to react to, editable and exportable as a live prototype. Under `claude.ai/design` it's the built-in `/design` skill (published as an Artifact) or a claude.ai/design project made by hand in the web app; under `stitch` it's a Stitch project.
-- **`design-system`**: a design-system project driven by **DesignSync** (the `/design-sync` skill plus the `claude-design` MCP), for a shared component library kept in sync.
+With **`artifacts`**, on the first UI screen trailhead attaches a canvas: **pick an existing one**, **paste a URL**, or **create a new one** (it asks you for the name), and caches its URL in `design.project`. Each screen (and each variant) is its own artboard, grouped in a canvas page per ticket; the design system in `design.system` (your account's default one, or the one you pick) is installed on the canvas so its colours, type and components are at hand. Approval messages carry the canvas URL plus the name of each artboard. Once you approve, trailhead **re-fetches** the artboards (in case you edited them live) before writing any UI code.
 
-On the first UI screen, trailhead attaches to a surface: for a **Stitch** project or a **claude.ai/design design-system**, it can **pick an existing one**, **paste a URL**, or **create a new one** (it asks you for the name); for a **claude.ai/design canvas** there is no create-via-MCP, so it uses the `/design` skill (an **Artifact**) or a web-app project whose `/p/<id>` URL you **paste**. It caches the chosen id/URL in `design.project`; a project already cached from before keeps the `design-system` surface unless you set `design.surface`, so existing setups don't change. Each screen is added there, and its URL is linked from the ticket. Once you approve, trailhead **re-fetches** the current design (in case you edited it live) before writing any UI code.
+With **`stitch`**, `design.surface` picks a Stitch project of screens (`canvas`, default) or a shared Stitch design system (`design-system`); trailhead picks, pastes or creates it the same way, and offers once to install the Stitch MCP if it isn't connected (decline and it falls back to local disk).
 
-If a hosted mode's MCP isn't connected, trailhead **offers to install it once** (`claude mcp add ...`); decline and it falls back to local disk. (The `claude.ai/design` **canvas** surface needs no MCP, so nothing is offered for it; only the **design-system** surface has an install offer.) On Codex, `claude.ai/design` isn't available, so trailhead offers to switch to `stitch` (cross-host) before falling to local disk. `design.approval` decides whether the build waits for your explicit go-ahead (`explicit`), or proceeds right after surfacing the mockup (`auto`); it doesn't affect the one-time install offer, which prompts either way.
+**Moving from claude.ai/design.** The standalone Claude Design site closes on 2026-12-14 and its designs now live in Claude as Artifacts. A config that still says `design: claude.ai/design` keeps working as `artifacts` (trailhead tells you once and offers to rewrite the key), but a cached claude.ai/design project can't be reused: migrate your design systems from the Artifacts page banner and let trailhead attach a new canvas. Where the `Artifact` tool isn't available (Codex, or an API-key session), trailhead offers to switch to `stitch` before falling to local disk. `design.approval` decides whether the build waits for your explicit go-ahead (`explicit`), or proceeds right after surfacing the mockup (`auto`).
 
 ---
 

package/bin/lib/codex-projection.js

@@ -115,8 +115,8 @@ The engine's \`/clear\` is Codex's \`/new\` (start a fresh session). Command ref
 ## F. Lifecycle hooks (native Codex hooks)
 Codex has a hook bus, so trailhead's guardrails run as **real Codex hooks**, not degraded prose. The installer registers them in \`~/.codex/hooks.json\`: commit-guard, secret-guard, install-guard and body-guard as \`PreToolUse\` (matcher \`Bash\`) hooks that can veto the command before it runs, secret-read-guard as a \`PreToolUse\` (matcher \`Read|Bash\`) hook that denies reads of \`.env\`/\`.env.*\`/\`.secrets\`, the injection-scanner as a \`PostToolUse\` (matcher \`Bash\`) advisory, mockup-link-stop as a \`Stop\` hook (when your final reply asks to approve a mockup without carrying its link, it continues the turn so you rewrite the ask with the URL or file path in the prose), and check-update as a \`SessionStart\` hook. On Codex, file reads happen through shell commands rather than a native Read-tool event, so the secret-read guard's enforcement here runs via its **Bash** arm (protection is not lost); the \`Read\` half of its matcher is a Claude-Code-native path, registered on Codex too only so it fires without changes if a future Codex version adds an equivalent event. search-guard is Claude-Code-specific (it only prevents arming Claude's \`Read()\` deny rule under bypass permissions, a mechanism Codex lacks), so it is not projected to Codex at all. They use the same wire format they use on Claude Code (JSON on stdin, a \`decision\`/\`permissionDecision\` verdict on stdout), which Codex accepts. The host-independent git \`commit-msg\` hook is still installed at repo first-use as well (defence in depth), exactly as on Claude. Codex gates hooks behind \`features.hooks = true\` and reviews them for trust on first start: the installer enables the flag, and Codex will ask you to trust trailhead's hooks the next time it starts.
 
-## G. Design / UI mockups -> local disk
-The \`claude.ai/design\` mockup mode (DesignSync: the \`claude_design\` MCP + the \`/design-sync\` skill) does not exist on Codex, so it **collapses to local-disk mockups** here: whatever \`config.design\` says, the Prototype technique's \`disk\` path is the only one available. Produce a throwaway static HTML mockup next to the code, link it from the ticket, and never attempt DesignSync / claude.ai/design on Codex (there is no \`claude_design\` MCP or \`/design-sync\` skill to call). \`config.design.approval\` still applies unchanged: \`explicit\` waits for the user's go-ahead before any UI code, \`auto\` surfaces the mockup and proceeds.
+## G. Design / UI mockups: artifacts -> stitch offer, else local disk
+The \`artifacts\` mockup mode (a Design canvas Artifact built with Claude Code's \`Artifact\` tool; the legacy \`claude.ai/design\` value means the same) does not exist on Codex: there is no \`Artifact\` tool here. When \`config.design\` names it, follow the Prototype technique's fallback: **offer once to switch this project to \`design: stitch\`** (the Google Stitch MCP runs on Codex too), and only on decline produce a throwaway static HTML mockup next to the code (\`disk\`), link it from the ticket, and say why. Never try to create or edit an Artifact on Codex. \`config.design.approval\` still applies unchanged: \`explicit\` waits for the user's go-ahead before any UI code, \`auto\` surfaces the mockup and proceeds.
 
 ## H. Shell timeouts & background jobs (plan-review's external CLIs)
 The **Cross-AI plan review** technique invokes each external reviewer CLI (\`codex exec\`, \`gemini -p\`, \`qwen -p\`, …) through Claude Code's **Bash tool**, and tells the engine to beat that tool's ~2-minute default cut by setting its \`timeout\` parameter to the 10-minute max, or launching the call with \`run_in_background: true\` and collecting it later. Those are Claude Bash-tool knobs with no Codex equivalent, so map the *intent* onto Codex's own shell/exec tool. Reviews never block the session (the engine's hard cross-host default), so **the default is to background the reviewers** and collect them by polling, never block on them: launch each with a trailing \`&\` (or your shell tool's background form), **redirect its stdin from \`/dev/null\` and its output to a file** (\`codex exec … "<prompt>" < /dev/null > out.txt 2>&1 &\`), and poll/collect when it finishes, so several reviewers run in parallel instead of serially eating the wall-clock; or wrap each reviewer invocation in a §D subagent so the long-running call sits behind the multi_agent poll loop. Where a reviewer must run synchronously instead, give that call its **own long timeout** (the \`timeout_ms\` / equivalent on Codex's shell/exec tool, set to several minutes, never the short default), so a reviewer that legitimately runs for minutes is not cut mid-review. Either way plan-review's own rule is unchanged: never rely on a short default timeout, retry once at the wide margin, then drop a still-slow reviewer rather than let it wedge the build. **Close the reviewer's stdin when backgrounding it** (\`< /dev/null\`): \`codex exec\` reads additional prompt input from stdin and blocks on EOF, so a backgrounded reviewer that inherits an open or attached stdin sits idle at "Reading additional input from stdin..." (0% CPU) forever instead of running (passing the prompt as an argument does not exempt it). Guard the poll loop too: a reviewer pinned at 0% CPU with no output past a threshold is stuck, so surface it and drop it after the one retry rather than reporting "still running" indefinitely. This is the external-CLI **shell** path; §D covers the separate **subagent** (\`wait_agent\`) path, and the two are distinct (an external reviewer CLI is a plain shell call, not a spawned Codex subagent).

package/bin/trailhead.test.js

@@ -123,6 +123,10 @@ const codexCommitMsgSync = path.join(codexDir, 'skills', 'trailhead', 'templates
 ok('codex: commit-msg-sync script projected', fs.existsSync(codexCommitMsgSync));
 ok('codex: commit-msg-sync script is byte-identical to source',
   fs.readFileSync(codexCommitMsgSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js'), 'utf8'));
+// Il sync del label guard (migrazione all'if a livello di job) viaggia con templates/.
+const codexLabelGuardSync = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-label-guard-sync.js');
+ok('codex: label-guard-sync script is byte-identical to source', fs.existsSync(codexLabelGuardSync) &&
+  fs.readFileSync(codexLabelGuardSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-label-guard-sync.js'), 'utf8'));
 // #193: the audit fast path / attribution walk script rides in templates/ on Codex too.
 const codexAuditWalk = path.join(codexDir, 'skills', 'trailhead', 'templates', 'trailhead-audit-walk.js');
 ok('codex: audit-walk script projected', fs.existsSync(codexAuditWalk));
@@ -870,6 +874,9 @@ const claudeCommitMsgSync = path.join(claudeDir, 'trailhead', 'templates', 'trai
 ok('claude: commit-msg-sync script projected', fs.existsSync(claudeCommitMsgSync));
 ok('claude: commit-msg-sync script is byte-identical to source',
   fs.readFileSync(claudeCommitMsgSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-commit-msg-sync.js'), 'utf8'));
+const claudeLabelGuardSync = path.join(claudeDir, 'trailhead', 'templates', 'trailhead-label-guard-sync.js');
+ok('claude: label-guard-sync script is byte-identical to source', fs.existsSync(claudeLabelGuardSync) &&
+  fs.readFileSync(claudeLabelGuardSync, 'utf8') === fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'templates', 'trailhead-label-guard-sync.js'), 'utf8'));
 const claudeAuditWalk = path.join(claudeDir, 'trailhead', 'templates', 'trailhead-audit-walk.js');
 ok('claude: audit-walk script projected', fs.existsSync(claudeAuditWalk));
 ok('claude: audit-walk script is byte-identical to source',
@@ -1159,6 +1166,14 @@ for (const [label, src] of [
   ok(`source: ${label} has no em-dash`, !src.includes('—'));
 }
 
+// --- label guard: setup e update rilevano/migrano un guard senza if a livello di job
+ok('source: teamwork.md references trailhead-label-guard-sync.js', teamworkSource.includes('trailhead-label-guard-sync.js'));
+ok('source: substrate-commands.md references trailhead-label-guard-sync.js', substrateCommandsSource.includes('trailhead-label-guard-sync.js'));
+ok('source: load-first.md runs the label guard check with --notice',
+  fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'skills', '_shared', 'load-first.md'), 'utf8').includes('trailhead-label-guard-sync.js --repo <project root> --notice'));
+ok('source: updating.md realigns the repo label guard',
+  fs.readFileSync(path.join(repoRoot, 'plugins', 'trailhead', 'skills', 'trailhead-manage', 'references', 'updating.md'), 'utf8').includes('label guard sync script'));
+
 // --- #189: script mancante / errore node -> fallback che ispeziona la hooks dir
 // invece di dichiarare alla cieca "git non applica le regole" ------------------
 ok('source: teamwork.md fallback resolves the hooks dir via rev-parse --git-path hooks',
@@ -1583,9 +1598,16 @@ const auditDescLine192 = (auditCmdSrc.match(/^description: (.+)$/m) || [])[1] ||
 ok('source: commands/audit.md description mentions regressions, starts "Audit and stays under 180 chars',
   /^"Audit /.test(auditDescLine192) && /regression/i.test(auditDescLine192) && auditDescLine192.length < 180);
 ok('source: manage SKILL.md describes the regression audit', /regression/i.test((manageSkillSrc190.match(/^description: .+$/m) || [''])[0]) || /regression/i.test((manageSkillSrc190.match(/\*\*`audit[^\n]*/) || [''])[0]));
-for (const doc of ['README.md', 'README.it.md', path.join('site', 'src', 'content', 'docs', 'docs', 'commands.md')]) {
-  const docSrc192 = fs.readFileSync(path.join(repoRoot, doc), 'utf8');
-  const auditPara192 = docSrc192.split('\n').filter((l) => l.includes('/trailhead:audit')).join('\n');
+// Il sito è diviso: commands.md è solo l'indice, il dettaglio di audit vive
+// nella sezione `### /trailhead:audit` della guida manage.
+const siteManageDoc = path.join('site', 'src', 'content', 'docs', 'docs', 'commands', 'manage.md');
+const auditMention = (doc) => {
+  const src = fs.readFileSync(path.join(repoRoot, doc), 'utf8');
+  if (doc === siteManageDoc) return (src.match(/### \/trailhead:audit[\s\S]*?(?=\n### |\nNext:|$)/) || [''])[0];
+  return src.split('\n').filter((l) => l.includes('/trailhead:audit')).join('\n');
+};
+for (const doc of ['README.md', 'README.it.md', siteManageDoc]) {
+  const auditPara192 = auditMention(doc);
   ok(`docs: ${doc} audit mention covers unchanged and evolved`, /unchanged|invariat/i.test(auditPara192) && /evolved|evolut/i.test(auditPara192));
 }
 
@@ -1622,9 +1644,8 @@ ok('source: auditing.md step 5 dispatches the agent-bound set and reads code at
 ok('source: auditing.md step 8 counts sum to the audited set with the light-check share',
   /light check/i.test(step8Slice192) && /light-check share/.test(step8Slice192) && /not implemented, unverifiable/.test(step8Slice192));
 ok('source: auditing.md step 10 flags unverifiable from step 4 or step 6', /\(step 4 or step 6\)/.test(step10Slice190));
-for (const doc of ['README.md', 'README.it.md', path.join('site', 'src', 'content', 'docs', 'docs', 'commands.md')]) {
-  const docSrc = fs.readFileSync(path.join(repoRoot, doc), 'utf8');
-  const para = docSrc.split('\n').filter((l) => l.includes('/trailhead:audit')).join('\n');
+for (const doc of ['README.md', 'README.it.md', siteManageDoc]) {
+  const para = auditMention(doc);
   ok(`docs: ${doc} audit mention names the Refs trailer fast path`, /Refs: #<n>/.test(para));
   ok(`docs: ${doc} audit mention covers tasks and prototypes in the light check`, /task/i.test(para) && /prototyp|prototipi/i.test(para));
 }

package/package.json

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

package/plugins/trailhead/hooks/lib/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/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.test.js

@@ -52,7 +52,7 @@ ok('mockup offer whose option description mentions approval is NOT an approval a
     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' },
+      { label: 'Prima un mockup', description: 'Disegno la pagina su un canvas Artifacts e attendo approvazione prima di scriverla' },
     ],
   }],
 }));
@@ -68,7 +68,7 @@ ok('unrelated ask is not detected', !isMockupApprovalAsk({
 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('https URL counts as a link', hasLink('Ecco: https://claude.ai/artifact/AbC123xyz'));
 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)'));
@@ -88,7 +88,7 @@ ok('prose right before the ask is collected', /pronto su MyApp/.test(proseBefore
 
 const linkBeforeTools = [
   userPrompt('lavora #12'),
-  text('Mockup: https://claude.ai/design/p/abc'),
+  text('Mockup: https://claude.ai/artifact/AbC123xyz'),
   toolUse('Bash'),
   toolResult('ok'),
   text('Pronto.'),
@@ -125,7 +125,7 @@ function runHook(payload) {
 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 withLink = [...failing.slice(0, 4), text('Mockup: https://claude.ai/artifact/AbC123xyz'), 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() === '');
 

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

@@ -19,7 +19,7 @@ const noLink = [
   '1. Approvo',
   '2. Chiedo modifiche',
 ].join('\n');
-const withLink = noLink.replace('pronto su MyApp', 'pronto: https://claude.ai/design/p/abc?file=faq.html');
+const withLink = noLink.replace('pronto su MyApp', 'pronto: https://claude.ai/artifact/AbC123xyz');
 
 // --- isMockupApprovalMessage ---
 ok('IT approval reply is detected', isMockupApprovalMessage(noLink));