@marcomigozzi/trailhead 0.10.0 → 0.11.1

package/README.it.md

@@ -260,7 +260,7 @@ Molte persone (e le loro sessioni di agente) condividono una mappa e la lavorano
 - **Split** un ticket sovradimensionato in figli e supersede l'originale (`/trailhead:split`).
 - **Pause/resume** tramite un commento di checkpoint `PAUSED`, così qualsiasi sessione può riprendere un ticket.
 - **Isola le sessioni concorrenti con i worktree.** Di default (`isolation: auto`) trailhead lo fa per te: al work-start di ogni ticket chiede se ne lavorerai più di uno alla volta e sceglie la modalità in base alla forma del repo. Per forzarla in anticipo, imposta `isolation: worktree` nell'header delle conventions, e ogni ticket in esecuzione gira nel proprio `git worktree` su un branch `trailhead/t<n>`, integrato di nuovo nel trunk al Resolve. Implica un branch per ticket anche sotto `git: main` (git non farà il checkout del trunk due volte), ed è la postura giusta per un **monorepo** (un worktree condivide l'object store, molto più economico di un secondo clone). Un'avvertenza: un worktree isola il *source* ma è un path nuovo senza dipendenze installate, quindi un **package legato a un path** (React Native/Expo, toolchain native, qualsiasi cosa legata a un `node_modules` locale) non buildera da lì. Per questi c'è **`isolation: clone`**: un clone dedicato per-ticket che installa le proprie dipendenze e builda/UATa come l'app vera (più pesante di un worktree, e lo strumento giusto per un submodule Expo/RN). Oppure tieni `isolation: none` e serializza. Altrimenti esegui le sessioni concorrenti in clone separati.
-- **Un marker session-ticket per la tua statusline.** Quando inizia a lavorare un ticket, trailhead deposita una riga singola, gitignorata, `.trailhead/session-ticket` (`#<n> <title>`) alla radice di lavoro e la pulisce all'handoff. È puramente un hint economico e offline così una statusline (o qualsiasi tool) può mostrare *su quale ticket è questa sessione* senza colpire il tracker; trailhead stesso continua a trattare le Issue come fonte di verità.
+- **Un marker session-ticket per la tua statusline.** Quando inizia a lavorare un ticket, trailhead deposita una riga singola, gitignorata, `.trailhead/session-ticket` (`#<n> <title>`) alla radice di lavoro e la pulisce all'handoff. È un hint economico e offline così una statusline (o qualsiasi tool) può mostrare *su quale ticket è questa sessione* senza colpire il tracker; trailhead stesso continua a trattare le Issue come fonte di verità. Fa anche di più: finché è presente, l'hook git commit-msg richiede che ogni commit porti un trailer `Refs: #<n>` corrispondente.
 - **Sceglie l'isolation per te di default (`auto`).** Senza un `isolation:` esplicito impostato (il default è `auto`), la prima volta che lavori un ticket trailhead chiede se ne lavorerai più di uno alla volta su questa macchina in questa sessione; se sì usa un `git worktree` (repo semplice) o un `clone` (superrepo con submodule), altrimenti lavora semplicemente nel checkout corrente. Non viene scritto nulla nelle conventions, e puoi comunque forzare `none`/`worktree`/`clone` esplicitamente.
 - **Dai scope ai ticket per path su un monorepo.** Un ticket può portare una riga `Scope:` che nomina il/i package/dir che tocca: scope disgiunti parallelizzano in sicurezza, e dà scope a build/test e ai commit del worktree limitandoli al package interessato. `/trailhead:adopt` rileva un monorepo e propone sia `isolation: worktree` sia la convenzione `Scope:`. Sotto `isolation: none`, `Scope:` **serializza** anche un'area condivisa: al momento del claim una sessione si trattiene se lo scope di un altro ticket in corso si sovrappone, così due ticket con scope sullo stesso submodule/package non possono girare insieme (è così che tieni due sessioni fuori da un'app legata a un path).
 - **I git submodule sono gestiti come repo separati.** Il lavoro che atterra dentro un submodule viene committato *dentro il submodule* (su un branch) e pubblicato prima che un bump del gitlink nel parent lo referenzi. Poiché i worktree del superproject condividono un unico git dir del submodule, un **repo con submodule risolve a `clone`** (sotto il default `auto`, o scalando un `worktree` esplicito), così ogni ticket ottiene uno stato del submodule indipendente; il clone provvede i suoi submodule al setup (`--recurse-submodules`) e il Verify controlla `git status` dentro ogni submodule toccato. Un ticket che copre due submodule resta atomico tramite un singolo commit del parent che bumpa entrambi i gitlink insieme; il suo `Scope:` li nomina entrambi, e lo stesso submodule conta come scope sovrapposto, quindi due ticket su di esso serializzano. `/trailhead:adopt` rileva `.gitmodules` e scrive la regola nelle conventions.
@@ -325,7 +325,7 @@ La **sessione principale resta l'orchestratore**. Tiene i momenti interattivi (i
 Esempio di file di config (la stessa forma funziona per il `.trailhead/config.json` di progetto e il `~/.claude/trailhead/config.json` globale):
 
 ```json
-{ "ticket": { "language": "en" }, "models": { "plan": "claude-opus-4-8", "execute": "claude-sonnet-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }
+{ "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`:

package/README.md

@@ -260,7 +260,7 @@ Many people (and their agent sessions) share one map and work it concurrently:
 - **Split** an oversized ticket into children and supersede the original (`/trailhead:split`).
 - **Pause/resume** via a `PAUSED` checkpoint comment, so any session can pick a ticket back up.
 - **Isolate concurrent sessions with worktrees.** By default (`isolation: auto`) trailhead does this for you: at each ticket's work-start it asks whether you'll run more than one at once and picks the mode by repo shape. To force it eagerly, set `isolation: worktree` in the conventions header, and each executing ticket runs in its own `git worktree` on a `trailhead/t<n>` branch, integrated back to the trunk at Resolve. It implies a branch per ticket even under `git: main` (git won't check the trunk out twice), and it is the right posture for a **monorepo** (a worktree shares the object store, far cheaper than a second clone). One caveat: a worktree isolates *source* but is a fresh path with no installed deps, so a **path-bound package** (React Native/Expo, native toolchains, anything tied to a local `node_modules`) won't build from it. For those there's **`isolation: clone`**: a dedicated per-ticket clone that installs its own deps and builds/UATs like the real app (heavier than a worktree, and the right tool for an Expo/RN submodule). Or keep `isolation: none` and serialize. Otherwise run concurrent sessions in separate clones.
-- **A session-ticket marker for your statusline.** When it starts working a ticket, trailhead drops a one-line, gitignored `.trailhead/session-ticket` (`#<n> <title>`) at the working root and clears it at handoff. It's purely a cheap, offline hint so a statusline (or any tool) can show *which ticket this session is on* without hitting the tracker; trailhead itself still treats the Issues as the source of truth.
+- **A session-ticket marker for your statusline.** When it starts working a ticket, trailhead drops a one-line, gitignored `.trailhead/session-ticket` (`#<n> <title>`) at the working root and clears it at handoff. It's a cheap, offline hint so a statusline (or any tool) can show *which ticket this session is on* without hitting the tracker; trailhead itself still treats the Issues as the source of truth. It also does more than that: while it's present, the git commit-msg hook requires every commit to carry a `Refs: #<n>` trailer matching it.
 - **It picks isolation for you by default (`auto`).** With no explicit `isolation:` set (the default is `auto`), the first time you work a ticket trailhead asks whether you'll work more than one at once on this machine this session; if so it uses a `git worktree` (plain repo) or a `clone` (submodule superrepo), otherwise it just works in the current checkout. Nothing is written into the conventions, and you can still force `none`/`worktree`/`clone` explicitly.
 - **Scope tickets by path on a monorepo.** A ticket can carry a `Scope:` line naming the package/dir(s) it touches: disjoint scopes parallelize safely, and it scopes build/test and the worktree's commits to the affected package. `/trailhead:adopt` detects a monorepo and proposes both `isolation: worktree` and the `Scope:` convention. Under `isolation: none`, `Scope:` also **serializes** a shared area: at claim time a session holds off if another in-progress ticket's scope overlaps, so two tickets scoped to the same submodule/package can't run at once (how you keep two sessions off one path-bound app).
 - **Git submodules are handled as separate repos.** Work that lands inside a submodule is committed *inside the submodule* (on a branch) and published before a gitlink bump in the parent points at it. Because superproject worktrees share one submodule git dir, a **submodule-bearing repo resolves to `clone`** (under the default `auto`, or by escalating an explicit `worktree`), so each ticket gets independent submodule state; the clone provisions its submodules at setup (`--recurse-submodules`) and Verify checks `git status` inside each touched submodule. A ticket spanning two submodules stays atomic via a single parent commit that bumps both gitlinks together; its `Scope:` names both, and the same submodule counts as overlapping scope, so two tickets on it serialise. `/trailhead:adopt` detects `.gitmodules` and writes the rule into the conventions.
@@ -325,7 +325,7 @@ The **main session stays the orchestrator**. It holds the interactive moments (a
 Example config file (the same shape works for the project `.trailhead/config.json` and the global `~/.claude/trailhead/config.json`):
 
 ```json
-{ "ticket": { "language": "en" }, "models": { "plan": "claude-opus-4-8", "execute": "claude-sonnet-5" }, "tdd": "seams", "acceptance": { "browser": "auto" } }
+{ "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`:

package/bin/lib/install-verify.js

@@ -0,0 +1,257 @@
+'use strict';
+// install-verify.js: post-install filesystem verification for both hosts.
+//
+// installClaude/installCodex place files and register hooks, but never
+// checked any of it landed. This module adds that check: given a spec
+// describing what an install is supposed to look like, it walks the
+// filesystem (and the host's hook registry file) and reports what's missing
+// or merely unverifiable (a registered hook target whose path depends on an
+// env var this process doesn't have set).
+//
+// Reads the filesystem only, never writes, and never throws: a stat/parse
+// error just counts as "missing" or an empty registry. It never reads
+// process.env or os.homedir() itself; the caller always passes both in
+// (spec.env, spec.home), so the tests stay hermetic.
+
+const fs = require('fs');
+const path = require('path');
+const { codexLayout } = require('./codex-projection.js');
+
+// --- fs probes, never throw --------------------------------------------------
+function isDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+function isFile(p) {
+  try { return fs.statSync(p).isFile(); } catch { return false; }
+}
+
+// --- sharedCoreFiles ----------------------------------------------------------
+// The shared-core file list, single-sourced from _shared/load-first.md's own
+// numbered "Load first, in order" list: load-first.md itself, plus every
+// `../_shared/<name>.md` named on a numbered-list line, de-duplicated, in
+// order. Empty/unreadable text still yields ['load-first.md'].
+function sharedCoreFiles(loadFirstText) {
+  const names = ['load-first.md'];
+  const re = /^\d+\.\s+`\.\.\/_shared\/([\w.-]+\.md)`/gm;
+  let m;
+  while ((m = re.exec(loadFirstText || '')) !== null) {
+    if (!names.includes(m[1])) names.push(m[1]);
+  }
+  return names;
+}
+
+// --- hookScriptTokens ---------------------------------------------------------
+// Split a shell-like command into tokens (quotes stripped), then return every
+// token whose basename matches trailhead-<name>.js. A1: a quoted token that
+// itself contains whitespace (e.g. bash -c's payload) is re-tokenized
+// recursively, so an inner script path nested inside `bash -c '...'` is still
+// found as its own token.
+function tokenize(command) {
+  const re = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  const tokens = [];
+  let m;
+  while ((m = re.exec(command)) !== null) {
+    tokens.push(m[1] !== undefined ? m[1] : (m[2] !== undefined ? m[2] : m[3]));
+  }
+  return tokens;
+}
+
+function hookScriptTokens(command) {
+  const found = [];
+  const visit = (cmd) => {
+    for (const token of tokenize(cmd)) {
+      if (/\s/.test(token)) {
+        visit(token);
+      } else if (/^trailhead-[\w-]+\.js$/.test(path.basename(token))) {
+        found.push(token);
+      }
+    }
+  };
+  visit(command || '');
+  return found;
+}
+
+// --- expandTarget --------------------------------------------------------------
+// Expand a `~`/`~/...` prefix (to `home`) and any `$VAR`/`${VAR}` references
+// (from `env`). The first undefined variable short-circuits to
+// { unresolved: varName }; an empty-string value counts as defined and is
+// substituted as-is. `~user/...` is intentionally NOT expanded (it stays
+// relative and later fails as a relative target).
+function expandTarget(token, { env, home }) {
+  let result = token;
+  if (result === '~' || result.startsWith('~/')) {
+    result = path.join(home, result.slice(1));
+  }
+  const re = /\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g;
+  let out = '';
+  let lastIndex = 0;
+  let match;
+  while ((match = re.exec(result)) !== null) {
+    const name = match[1] || match[2];
+    const val = env[name];
+    if (val === undefined) return { unresolved: name };
+    out += result.slice(lastIndex, match.index) + val;
+    lastIndex = match.index + match[0].length;
+  }
+  out += result.slice(lastIndex);
+  return { path: out };
+}
+
+// --- verifyInstall: individual checks -----------------------------------------
+function checkSkills(spec, missing) {
+  for (const name of spec.skillDirs) {
+    if (name === '_shared') continue;
+    const skillMd = path.join(spec.skillsRoot, name, 'SKILL.md');
+    if (!isDir(path.join(spec.skillsRoot, name)) || !isFile(skillMd)) {
+      missing.push(`skill ${name}/SKILL.md`);
+    }
+  }
+}
+
+function checkSharedCore(spec, missing) {
+  const sharedDir = path.join(spec.skillsRoot, '_shared');
+  for (const f of spec.sharedFiles) {
+    if (!isDir(sharedDir) || !isFile(path.join(sharedDir, f))) missing.push(`shared core _shared/${f}`);
+  }
+}
+
+function checkHookScripts(spec, missing) {
+  for (const f of spec.hookFiles) {
+    if (!isFile(path.join(spec.hooksDir, f))) missing.push(`hook script ${f}`);
+  }
+  for (const f of spec.hookLibFiles) {
+    if (!isFile(path.join(spec.hooksDir, 'lib', f))) missing.push(`hook lib lib/${f}`);
+  }
+}
+
+function readRegistry(registryFile) {
+  try { return JSON.parse(fs.readFileSync(registryFile, 'utf8')); } catch { return {}; }
+}
+
+// Registered hook targets + expected registration. Walks hooks.<event>[].hooks[]
+// .command in the registry file, expands each trailhead-* token, and sorts it
+// into `missing` (relative or non-existent) or `unverified` (undefined var).
+// Then, per A2, an expected hookFiles entry counts as registered when some
+// token expands to exactly hooksDir/<f>, OR an unresolved token's basename is
+// <f> (stays warning-only, never also missing).
+function checkRegisteredTargets(spec, missing, unverified) {
+  const registry = readRegistry(spec.registryFile);
+  const registryName = path.basename(spec.registryFile);
+  const events = (registry && typeof registry.hooks === 'object' && registry.hooks) ? registry.hooks : {};
+  const registeredExact = new Set();
+  const registeredViaUnresolved = new Set();
+
+  for (const [event, groups] of Object.entries(events)) {
+    for (const group of Array.isArray(groups) ? groups : []) {
+      for (const hook of Array.isArray(group.hooks) ? group.hooks : []) {
+        const command = typeof hook.command === 'string' ? hook.command : '';
+        for (const token of hookScriptTokens(command)) {
+          const expanded = expandTarget(token, { env: spec.env, home: spec.home });
+          if (expanded.unresolved) {
+            unverified.push(`${token} (${event}, ${registryName}: $${expanded.unresolved} undefined)`);
+            registeredViaUnresolved.add(path.basename(token));
+            continue;
+          }
+          if (!path.isAbsolute(expanded.path)) {
+            missing.push(`registered hook target ${token} is relative (${event}, ${registryName})`);
+            continue;
+          }
+          if (!isFile(expanded.path)) {
+            missing.push(`registered hook target ${expanded.path} (${event}, ${registryName})`);
+            continue;
+          }
+          for (const f of spec.hookFiles) {
+            if (expanded.path === path.join(spec.hooksDir, f)) registeredExact.add(f);
+          }
+        }
+      }
+    }
+  }
+
+  for (const f of spec.hookFiles) {
+    if (!registeredExact.has(f) && !registeredViaUnresolved.has(f)) {
+      missing.push(`hook registration ${f} (${registryName})`);
+    }
+  }
+}
+
+function checkAgents(spec, missing) {
+  let files = [];
+  if (isDir(spec.agentsDir)) {
+    try { files = fs.readdirSync(spec.agentsDir); } catch { files = []; }
+  }
+  const hasMatch = files.some((f) => spec.agentPattern.test(f) && isFile(path.join(spec.agentsDir, f)));
+  if (!hasMatch) missing.push(`agents: no trailhead-* agents in ${spec.agentsDir}`);
+}
+
+// --- verifyInstall --------------------------------------------------------------
+// spec = { skillsRoot, skillDirs, sharedFiles, hooksDir, hookFiles,
+//          hookLibFiles, registryFile, agentsDir, agentPattern, env, home }
+function verifyInstall(spec) {
+  const missing = [];
+  const unverified = [];
+  checkSkills(spec, missing);
+  checkSharedCore(spec, missing);
+  checkHookScripts(spec, missing);
+  checkRegisteredTargets(spec, missing, unverified);
+  checkAgents(spec, missing);
+  return { missing, unverified };
+}
+
+// --- spec builders ---------------------------------------------------------
+function claudeVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+  return {
+    skillsRoot: path.join(configDir, 'skills'),
+    skillDirs,
+    sharedFiles,
+    hooksDir: path.join(configDir, 'hooks'),
+    hookFiles,
+    hookLibFiles,
+    registryFile: path.join(configDir, 'settings.json'),
+    agentsDir: path.join(configDir, 'agents'),
+    agentPattern: /^trailhead-.*\.md$/,
+    env,
+    home,
+  };
+}
+
+function codexVerifySpec(configDir, { skillDirs, sharedFiles, hookFiles, hookLibFiles, env, home }) {
+  const L = codexLayout(configDir);
+  return {
+    skillsRoot: L.skillsRoot,
+    skillDirs,
+    sharedFiles,
+    hooksDir: L.hooksScriptsDir,
+    hookFiles,
+    hookLibFiles,
+    registryFile: L.hooksJson,
+    agentsDir: L.codexAgentsDir,
+    agentPattern: /^trailhead-.*\.toml$/,
+    env,
+    home,
+  };
+}
+
+// --- formatters --------------------------------------------------------------
+function formatVerifyFailure(hostLabel, configDir, { missing, unverified }) {
+  const lines = [`✗ trailhead install incomplete for ${hostLabel} → ${configDir}`];
+  for (const m of missing) lines.push(`  missing: ${m}`);
+  for (const u of unverified) lines.push(`  unverified: ${u}`);
+  lines.push('Re-run the installer to restore a missing file. For a stale or relative hook target, remove that entry from the registry file named above (or run --uninstall), then reinstall.');
+  return lines.join('\n');
+}
+
+function formatVerifyWarnings(unverified) {
+  return unverified.map((u) => `  ⚠ unverified hook target ${u}`);
+}
+
+module.exports = {
+  sharedCoreFiles,
+  hookScriptTokens,
+  expandTarget,
+  verifyInstall,
+  claudeVerifySpec,
+  codexVerifySpec,
+  formatVerifyFailure,
+  formatVerifyWarnings,
+};