@marcomigozzi/trailhead 0.1.0 → 0.3.0

package/plugins/trailhead/skills/trailhead/references/techniques/research.md

@@ -1,11 +1,11 @@
 # Research
-Spawn a focused subagent (AFK, parallelisable) with exactly ONE clear question — sharp enough that the answer is a decision, not a survey. Vague scope breeds rabbit holes; a narrow question is its own leash.
+Spawn a focused subagent (AFK, parallelisable) with exactly ONE clear question: sharp enough that the answer is a decision, not a survey. Vague scope breeds rabbit holes; a narrow question is its own leash. Spawn it as the built-in **`general-purpose`** agent (it writes findings to a throwaway `research/<name>` branch, so it needs Write); **never** a specialised researcher agent that another installed tool registered.
 
-- **Treat your own prior knowledge as hypothesis, not fact** — training is stale. "As of my training" is a warning flag, not a citation.
-- **Chase primary, high-trust sources**: official docs, source code, specs, first-party APIs — never a secondary write-up. Follow every claim back to the source that owns it; resolve *current* docs rather than reciting from memory.
+- **Treat your own prior knowledge as hypothesis, not fact**: training is stale. "As of my training" is a warning flag, not a citation.
+- **Chase primary, high-trust sources**: official docs, source code, specs, first-party APIs; never a secondary write-up. Follow every claim back to the source that owns it; resolve *current* docs rather than reciting from memory.
 - **Verify before asserting.** Cross-reference critical claims across sources: official docs (primary), release notes (currency), one more (confirmation). Check version numbers and dates.
-- **Guard the classic traps:** a negative claim ("X isn't possible") needs official verification, not a failed search — "didn't find it" ≠ "doesn't exist"; old docs may describe a deprecated path (check the changelog); verify ALL config scopes before ruling one out.
-- **Distinguish verified fact from inference explicitly.** Assign honest confidence (LOW when only training data backs a claim). "I couldn't find X", "sources contradict", "LOW confidence" are valuable findings, not failures — never hide uncertainty behind confident prose.
-- **Investigation, not confirmation:** gather evidence, then conclude — don't start from the answer you want and collect support.
-- Capture findings as a durable Markdown artifact on a throwaway `research/<name>` branch (out of main), each claim carrying its source URL; leave a pointer on the ticket. Return a **decision-ready answer** — verdict, tradeoffs, confidence, citations — not a raw data dump.
+- **Guard the classic traps:** a negative claim ("X isn't possible") needs official verification, not a failed search; "didn't find it" ≠ "doesn't exist"; old docs may describe a deprecated path (check the changelog); verify ALL config scopes before ruling one out.
+- **Distinguish verified fact from inference explicitly.** Assign honest confidence (LOW when only training data backs a claim). "I couldn't find X", "sources contradict", "LOW confidence" are valuable findings, not failures; never hide uncertainty behind confident prose.
+- **Investigation, not confirmation:** gather evidence, then conclude; don't start from the answer you want and collect support.
+- Capture findings as a durable Markdown artifact on a throwaway `research/<name>` branch (out of main), each claim carrying its source URL; leave a pointer on the ticket. Return a **decision-ready answer** (verdict, tradeoffs, confidence, citations) not a raw data dump.
 

package/plugins/trailhead/skills/trailhead/references/techniques/tdd.md

@@ -1,11 +1,11 @@
 # TDD
-Use TDD wherever behaviour has a definable input→output: business logic, parsers, validators, transforms, algorithms, state machines, API contracts. The gate: can you write `expect(fn(input)).toBe(output)` before `fn` exists? If yes, go test-first. Skip it for UI layout/styling, config, glue, one-off scripts, trivial CRUD, and exploratory spikes — add tests after if they earn their keep.
+Use TDD wherever behaviour has a definable input→output: business logic, parsers, validators, transforms, algorithms, state machines, API contracts. The gate: can you write `expect(fn(input)).toBe(output)` before `fn` exists? If yes, go test-first. Skip it for UI layout/styling, config, glue, one-off scripts, trivial CRUD, and exploratory spikes; add tests after if they earn their keep.
 
-Before writing any test, name the **seams** — the public boundaries where behaviour is observable without reaching inside — and confirm them. Tests live at seams, never against internals. Work in vertical slices, one behaviour at a time: one test → one implementation → repeat. Never write all tests then all code (that tests *imagined* behaviour and locks in structure you don't yet understand).
+Before writing any test, name the **seams** (the public boundaries where behaviour is observable without reaching inside) and confirm them. Tests live at seams, never against internals. Work in vertical slices, one behaviour at a time: one test → one implementation → repeat. Never write all tests then all code (that tests *imagined* behaviour and locks in structure you don't yet understand).
 
-- **RED** — one failing test that pins the intended behaviour as a specification (`should reject empty email`, not `test1`). Run it; SEE it fail for the *right reason* — a real assertion mismatch, not an import/syntax error. If it passes before you write code, STOP: the feature already exists or the test is wrong. Commit `test(...): add failing test for X`.
-- **GREEN** — the minimal code to pass. No cleverness, no speculative features, no anticipating future tests. If unrelated tests break, stop and investigate coupling. Commit `feat(...): implement X`.
-- **REFACTOR** — only with tests green, clean up; rerun — tests MUST still pass or you undo and go smaller. Commit if changed: `refactor(...): clean up X`.
+- **RED**: one failing test that pins the intended behaviour as a specification (`should reject empty email`, not `test1`). Run it; SEE it fail for the *right reason*: a real assertion mismatch, not an import/syntax error. If it passes before you write code, STOP: the feature already exists or the test is wrong. Commit `test(...): add failing test for X`.
+- **GREEN**: the minimal code to pass. No cleverness, no speculative features, no anticipating future tests. If unrelated tests break, stop and investigate coupling. Commit `feat(...): implement X`.
+- **REFACTOR**: only with tests green, clean up; rerun. Tests MUST still pass or you undo and go smaller. Commit if changed: `refactor(...): clean up X`.
 
-A good test verifies behaviour through the public interface and survives refactors. Reject **implementation-coupled** tests (mock internal collaborators, assert private state, hit the DB not the interface — break on refactor though behaviour didn't) and **tautological** tests (recompute the expected value the way the code does — expected values come from an independent source: a known-good literal, a worked example, the spec). Prefer integration tests exercising real seams over isolated unit mocks. The discipline is absolute: **no implementation code before a failing test exists.**
+A good test verifies behaviour through the public interface and survives refactors. Reject **implementation-coupled** tests (mock internal collaborators, assert private state, hit the DB not the interface; break on refactor though behaviour didn't) and **tautological** tests (recompute the expected value the way the code does; expected values come from an independent source: a known-good literal, a worked example, the spec). Prefer integration tests exercising real seams over isolated unit mocks. **Mock only at system boundaries** (external APIs, the DB, the clock, randomness, the filesystem) and never your own code: needing to mock an internal collaborator is a design smell, so inject the dependency instead. Design for testability: accept dependencies rather than construct them, return results rather than fire side effects, keep the seam's surface small. The discipline is absolute: **no implementation code before a failing test exists.**
 

package/plugins/trailhead/skills/trailhead/references/updating.md

@@ -0,0 +1,42 @@
+# Updating trailhead
+
+`/trailhead:update` checks whether a newer trailhead exists and installs it **where that is safe**. The version check itself is deterministic (a shipped script, not a guess): the **`trailhead-check-update.js`** SessionStart hook writes a cache the statusline and this command read.
+
+## 1. Read the check cache (refresh it if stale)
+
+Read `${XDG_CACHE_HOME:-~/.cache}/trailhead/update-check.json`. It carries `{channel, installed, latest, updateAvailable, where, checkedAt}`. If it is **missing or older than a few hours**, refresh it first by running the check hook and re-reading:
+
+```bash
+# prefer the installed hook; on a dev-symlink install it may only live in the repo
+HOOK="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/trailhead-check-update.js"
+[ -f "$HOOK" ] || HOOK="<repoRoot>/plugins/trailhead/hooks/trailhead-check-update.js"   # `where` from the cache is the repo root on dev
+rm -f "${XDG_CACHE_HOME:-$HOME/.cache}/trailhead/update-check.json"   # force a fresh check (bypass the 6h throttle)
+node "$HOOK"
+```
+
+If after this the cache still can't be read (no network, npm/gh unavailable), say so and stop: don't guess a version.
+
+## 2. If already current, stop
+
+If `updateAvailable` is `false`, tell the user they're on the latest (`installed` == `latest`) and stop. Nothing to do.
+
+## 3. If newer, confirm, then install per channel
+
+Show `installed → latest` and **confirm before touching anything** (auto-install, but with a go-ahead). Then act on `channel`:
+
+- **`dev`** (skill symlinked to a checkout): the code is a git repo at `where`. Update in place:
+  ```bash
+  git -C "<where>" pull --ff-only
+  ```
+  Edits go live through the symlink, no reinstall needed. If the pull isn't fast-forwardable (local commits/changes), **stop and tell the user** rather than forcing it; let them reconcile.
+- **`npm`** (installed via `npx @marcomigozzi/trailhead`): re-run the installer at the latest version, which copies the new files idempotently:
+  ```bash
+  npx -y @marcomigozzi/trailhead@latest
+  ```
+- **`plugin`** (installed via the Claude Code marketplace): the update is a **Claude Code command**, which this session cannot run for the user. Tell them to run **`/plugin update trailhead`** themselves (and `/plugin marketplace update trailhead` first if the marketplace is stale).
+
+## 4. After a successful auto-update
+
+For `dev`/`npm`, once the update lands: **refresh the check cache** so the statusline's `⬆` flag clears (`rm` the cache and re-run the hook, as in step 1), then tell the user to **restart or reload the agent** so the new skill, commands, and hooks are picked up. Report the new version plainly (`now on <latest>`).
+
+Never edit `package.json`/`plugin.json` versions here: this command **consumes** releases, it does not cut them.

package/plugins/trailhead/templates/statusline-trailhead.sh

@@ -0,0 +1,344 @@
+#!/usr/bin/env bash
+# Statusline trailhead-aware: "modello | progetto | branch | ticket | contesto | usage"
+#
+# Legge su stdin il JSON che Claude Code passa alle statusline
+# (.model.display_name, .model.id, .workspace.current_dir, .cwd, .transcript_path).
+#
+# Ticket in lavorazione: marker locale `.trailhead/session-ticket` (scritto da
+# trailhead al work-start, porta anche il titolo) -> numero dal branch
+# `trailhead/t<N>` -> titolo via `gh` in cache/background (solo se origin GitHub).
+#
+# Contesto: barra `[BARRA] Nk/Mk (P%)`, dall'ultimo usage del transcript. Tetto:
+# $CONTEXT_LIMIT -> .model.context_window -> tabella modello -> auto-bump 1M.
+#
+# Usage: % REALE del piano via l'API OAuth di Anthropic (come ccstatusline):
+# GET https://api.anthropic.com/api/oauth/usage con il Bearer preso da
+# ~/.claude/.credentials.json (claudeAiOauth.accessToken). Mostra la finestra
+# 5h e la settimana (7 giorni) piu' il reset. Cache ~60s, chiamata in background
+# (il render non aspetta la rete). Disabilita con TRAILHEAD_STATUSLINE_USAGE=0.
+#
+# Uso:
+#   - standalone: settings.json -> statusLine.command = "bash ~/.claude/statusline-trailhead.sh"
+#   - widget singolo (ccstatusline custom command): "--ticket-only" | "--context-only" | "--usage-only"
+
+set -uo pipefail
+
+MODE="${1:-full}"
+input="$(cat)"
+
+j() { printf '%s' "$input" | jq -r "$1 // empty" 2>/dev/null; }
+
+# --- colori ANSI (disattivabili con NO_COLOR) ---
+if [ -n "${NO_COLOR:-}" ]; then
+  C_RST= ; C_SEP= ; C_MODEL= ; C_PROJ= ; C_BRANCH= ; C_TICKET= ; C_CTX= ; C_5H= ; C_RESET= ; C_7D= ; C_UPDATE=
+else
+  e=$'\033['
+  C_RST="${e}0m"        # reset
+  C_SEP="${e}90m"       # separatori: grigio
+  C_MODEL="${e}36m"     # modello: cyan
+  C_PROJ="${e}94m"      # progetto: blu chiaro
+  C_BRANCH="${e}92m"    # branch: verde chiaro
+  C_TICKET="${e}93m"    # ticket: giallo chiaro
+  C_CTX="${e}95m"       # contesto: magenta chiaro
+  C_5H="${e}33m"        # finestra 5h: giallo
+  C_RESET="${e}32m"     # reset: verde
+  C_7D="${e}96m"        # settimana: cyan chiaro
+  C_UPDATE="${e}91m"    # aggiornamento disponibile: rosso chiaro
+fi
+
+# --- modello ---
+MODEL="$(j '.model.display_name')"
+TRANSCRIPT="$(j '.transcript_path')"
+
+# --- directory di lavoro ---
+DIR="$(j '.workspace.current_dir')"
+[ -z "$DIR" ] && DIR="$(j '.cwd')"
+[ -z "$DIR" ] && DIR="$PWD"
+
+# --- repo root + nome progetto ---
+ROOT="$(git -C "$DIR" rev-parse --show-toplevel 2>/dev/null || printf '%s' "$DIR")"
+PROJ="$(basename "$ROOT")"
+
+# --- branch (con gestione detached HEAD) ---
+BRANCH="$(git -C "$DIR" rev-parse --abbrev-ref HEAD 2>/dev/null)"
+[ "$BRANCH" = "HEAD" ] && BRANCH="@$(git -C "$DIR" rev-parse --short HEAD 2>/dev/null)"
+
+# --- ticket in lavorazione ---
+TICKET_N=""
+TITLE=""
+MARKER="$ROOT/.trailhead/session-ticket"
+if [ -f "$MARKER" ]; then
+  line="$(head -1 "$MARKER" 2>/dev/null)"
+  TICKET_N="$(printf '%s' "$line" | grep -oE '[0-9]+' | head -1)"
+  TITLE="$(printf '%s' "$line" | sed -E 's/^[^0-9]*[0-9]+[[:space:]]*//')"
+elif [[ "$BRANCH" =~ trailhead/t([0-9]+) ]]; then
+  TICKET_N="${BASH_REMATCH[1]}"
+fi
+
+# --- titolo via gh, solo se manca e se l'origin e' GitHub (cache + background) ---
+if [ -n "$TICKET_N" ] && [ -z "$TITLE" ] && command -v gh >/dev/null 2>&1; then
+  ORIGIN="$(git -C "$ROOT" remote get-url origin 2>/dev/null)"
+  REPO=""
+  case "$ORIGIN" in
+    *github.com[:/]*) REPO="$(printf '%s' "$ORIGIN" | sed -E 's#.*github\.com[:/]([^/]+/[^/.]+)(\.git)?/?$#\1#')" ;;
+  esac
+  if [ -n "$REPO" ]; then
+    CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/trailhead-statusline"
+    mkdir -p "$CACHE" 2>/dev/null
+    CF="$CACHE/$(printf '%s' "$REPO" | tr -c 'a-zA-Z0-9' '_')_${TICKET_N}.title"
+    [ -f "$CF" ] && TITLE="$(cat "$CF" 2>/dev/null)"
+    if [ ! -f "$CF" ] || [ -n "$(find "$CF" -mmin +10 2>/dev/null)" ]; then
+      ( t="$(gh issue view "$TICKET_N" -R "$REPO" --json title -q .title 2>/dev/null)" \
+          && [ -n "$t" ] && printf '%s' "$t" > "$CF" ) >/dev/null 2>&1 &
+    fi
+  fi
+fi
+
+# --- composizione ticket ---
+TICKET=""
+if [ -n "$TICKET_N" ]; then
+  if [ -n "$TITLE" ]; then
+    # titolo intero di default (riga 2 dedicata); tetto opzionale con TICKET_TITLE_MAX
+    TMAX="${TICKET_TITLE_MAX:-}"
+    [ -n "$TMAX" ] && [ "${#TITLE}" -gt "$TMAX" ] && TITLE="${TITLE:0:$((TMAX-1))}…"
+    TICKET="#${TICKET_N} ${TITLE}"
+  else
+    TICKET="#${TICKET_N}"
+  fi
+fi
+
+# --- barra dimensione contesto: "[BARRA] 364k/1000k (36%)" ---
+# Fonte primaria (come ccstatusline): .context_window del JSON di Claude Code
+# (context_window_size = tetto reale, current_usage = token). Fallback: ultimo
+# usage del transcript + tabella modello. $CONTEXT_LIMIT forza il tetto.
+# Denominatore = finestra * 0.8 (soglia auto-compact, come ccstatusline); il
+# rapporto e' regolabile con CONTEXT_USABLE_RATIO (1 = tetto pieno).
+CTX="$(
+  { [ -n "$TRANSCRIPT" ] && [ -f "$TRANSCRIPT" ] && tail -n 300 "$TRANSCRIPT" 2>/dev/null | tac | grep -m1 'cache_read_input_tokens'; } | \
+  CTX_MODEL_ID="$(j '.model.id')" \
+  CTX_CW_SIZE="$(j '.context_window.context_window_size')" \
+  CTX_USAGE="$(printf '%s' "$input" | jq -c '.context_window.current_usage // empty' 2>/dev/null)" \
+  python3 -c '
+import sys, os, json, re
+
+def as_int(x):
+    try: return int(float(x))
+    except Exception: return 0
+
+def sum_usage(u):
+    # "context length" = input + cache_creation + cache_read (esclude output), come ccstatusline
+    if isinstance(u, (int, float)):
+        return int(u)
+    if isinstance(u, dict):
+        return (as_int(u.get("input_tokens")) + as_int(u.get("cache_creation_input_tokens"))
+                + as_int(u.get("cache_read_input_tokens")))
+    return 0
+
+tok = 0
+# 1) fonte primaria: .context_window.current_usage dal JSON di Claude Code
+cw = os.environ.get("CTX_USAGE","")
+if cw:
+    try: tok = sum_usage(json.loads(cw))
+    except Exception: tok = 0
+# 2) fallback: ultimo usage del transcript
+if tok <= 0:
+    line = sys.stdin.readline()
+    if line:
+        try:
+            u = json.loads(line).get("message", {}).get("usage", {})
+        except Exception:
+            m = re.search(r"\"usage\":\{.*?\}\}", line) or re.search(r"\"usage\":\{[^}]*\}", line)
+            u = json.loads("{"+m.group(0)+"}")["usage"] if m else {}
+        tok = sum_usage(u)
+if tok <= 0:
+    raise SystemExit
+
+# tetto: CONTEXT_LIMIT (override) > context_window_size (autorevole) > tabella modello
+limit = as_int(os.environ.get("CONTEXT_LIMIT"))
+if not limit:
+    limit = as_int(os.environ.get("CTX_CW_SIZE"))
+if not limit:
+    mid = (os.environ.get("CTX_MODEL_ID") or "").lower()
+    table = [("haiku",200000),("sonnet",200000),("opus",200000)]
+    limit = next((v for k,v in table if k in mid), 200000)
+    if tok > limit and limit <= 200000:   # auto-bump 1M solo nel fallback
+        limit = 1000000
+
+# soglia usabile (auto-compact): denominatore = finestra * ratio (0.8 come ccstatusline)
+try:
+    ratio = float(os.environ.get("CONTEXT_USABLE_RATIO") or 0.8)
+except Exception:
+    ratio = 0.8
+denom = round(limit * ratio) if limit else 0
+pct = min(100, round(tok*100/denom)) if denom else 0   # % contro la soglia 0.8
+n = 10; filled = round(pct*n/100)
+bar = "█"*filled + "░"*(n-filled)
+# numeri REALI: token effettivi / tetto pieno; la percentuale riflette auto-compact 0.8
+print(f"[{bar}] {round(tok/1000)}k/{round(limit/1000)}k ({pct}%)")
+' 2>/dev/null
+)"
+
+# --- usage: % reale del piano via l'API OAuth di Anthropic (come ccstatusline) ---
+# five_hour.utilization (finestra 5h) e seven_day.utilization (settimana), piu' i reset.
+# Backoff variabile (come ccstatusline): cache success 180s; su 429 rispetta l'header
+# Retry-After (default 300s); altri errori 30s. Timeout 5s (USAGE_API_TIMEOUT lo cambia).
+# Chiamata in background: il render non attende mai. Off con TRAILHEAD_STATUSLINE_USAGE=0.
+USAGE_RAW=""
+CREDS="$HOME/.claude/.credentials.json"
+if [ "${TRAILHEAD_STATUSLINE_USAGE:-1}" != "0" ] && [ -f "$CREDS" ]; then
+  CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/trailhead-statusline"
+  mkdir -p "$CACHE" 2>/dev/null
+  UF="$CACHE/usage.txt"
+  # cache RAW (una parte per riga, senza colori): i colori si applicano al render
+  [ -f "$UF" ] && USAGE_RAW="$(cat "$UF" 2>/dev/null)"
+  # refresh solo dopo il "next" (epoch): backoff diverso per success / 429 / errore
+  NOW="$(date +%s)"; NEXT=0
+  [ -f "$UF.next" ] && NEXT="$(tr -dc 0-9 < "$UF.next" 2>/dev/null)"
+  [ -z "$NEXT" ] && NEXT=0
+  if [ "$NOW" -ge "$NEXT" ]; then
+    # lock atomico (mkdir): con piu' terminali che renderizzano insieme, un solo
+    # processo acquisisce e chiama; gli altri saltano. Il background rilascia il
+    # lock a fine chiamata. Rimuovo prima un lock stantio (processo morto, >60s).
+    LOCK="$CACHE/.lock"
+    [ -d "$LOCK" ] && [ -n "$(find "$LOCK" -maxdepth 0 -mmin +1 2>/dev/null)" ] && rmdir "$LOCK" 2>/dev/null
+    if command mkdir "$LOCK" 2>/dev/null; then
+    printf '%s' "$((NOW + 15))" > "$UF.next" 2>/dev/null
+    ( UF="$UF" CREDS="$CREDS" USAGE_TIMEOUT="${USAGE_API_TIMEOUT:-5}" python3 - >/dev/null 2>&1 <<'PY'
+import os, json, time, datetime, urllib.request, urllib.error
+uf = os.environ["UF"]; creds = os.environ["CREDS"]
+now = int(time.time())
+try: timeout = float(os.environ.get("USAGE_TIMEOUT") or 5)
+except Exception: timeout = 5
+
+def set_next(ttl):
+    try:
+        with open(uf + ".next", "w") as f:
+            f.write(str(now + int(ttl)))
+    except Exception:
+        pass
+
+try:
+    o = json.load(open(creds)).get("claudeAiOauth", {})
+    tok = o.get("accessToken")
+    if not tok:
+        set_next(60); raise SystemExit
+    req = urllib.request.Request(
+        "https://api.anthropic.com/api/oauth/usage",
+        headers={"Authorization": f"Bearer {tok}", "anthropic-beta": "oauth-2025-04-20"})
+    r = json.load(urllib.request.urlopen(req, timeout=timeout))
+    parts = []  # RAW, una per riga; i colori li mette bash al render
+    fh = r.get("five_hour") or {}
+    if fh.get("utilization") is not None:
+        parts.append(f"5h ({round(fh['utilization'])}%)")
+        ra = fh.get("resets_at")
+        if ra:
+            try:
+                t = datetime.datetime.fromisoformat(str(ra).replace("Z", "+00:00"))
+                mins = int((t - datetime.datetime.now(datetime.timezone.utc)).total_seconds() // 60)
+                if mins > 0:
+                    parts.append(f"⏳ {mins//60}h{mins%60:02d}m")
+            except Exception:
+                pass
+    sd = r.get("seven_day") or {}
+    if sd.get("utilization") is not None:
+        parts.append(f"7d ({round(sd['utilization'])}%)")
+    out = "\n".join(parts)
+    if out:
+        with open(uf + ".tmp", "w") as f:
+            f.write(out)
+        os.replace(uf + ".tmp", uf)
+    set_next(180)                       # success: 3 min (come ccstatusline)
+except urllib.error.HTTPError as e:
+    if e.code == 429:                   # rate limit: Retry-After (>0) o default 300s
+        ra = e.headers.get("Retry-After") if e.headers else None
+        ttl = 300
+        try:
+            v = int(str(ra).strip())
+            if v > 0: ttl = v
+        except Exception:
+            pass
+        set_next(ttl)
+    else:
+        set_next(30)                    # altri errori HTTP
+except SystemExit:
+    pass
+except Exception:
+    set_next(30)                        # timeout / rete / parse
+PY
+      rmdir "$LOCK" 2>/dev/null
+    ) >/dev/null 2>&1 &
+    fi
+  fi
+fi
+
+# --- colora le parti dell'usage al render (cache RAW -> segmenti colorati) ---
+USAGE=""
+if [ -n "$USAGE_RAW" ]; then
+  while IFS= read -r part; do
+    [ -z "$part" ] && continue
+    case "$part" in
+      "5h "*)  c="$C_5H" ;;
+      "⏳"*)   c="$C_RESET" ;;
+      "7d "*)  c="$C_7D" ;;
+      *)       c="" ;;
+    esac
+    if [ -z "$USAGE" ]; then
+      USAGE="${c}${part}${C_RST}"
+    else
+      USAGE="${USAGE}${C_SEP} | ${C_RST}${c}${part}${C_RST}"
+    fi
+  done <<< "$USAGE_RAW"
+fi
+
+# --- output ---
+if [ "$MODE" = "--ticket-only" ]; then
+  printf '%s\n' "$TICKET"; exit 0
+fi
+if [ "$MODE" = "--context-only" ]; then
+  printf '%s\n' "$CTX"; exit 0
+fi
+if [ "$MODE" = "--usage-only" ]; then
+  printf '%s\n' "$USAGE"; exit 0
+fi
+
+# --- aggiornamento trailhead disponibile (dalla cache scritta dall'hook SessionStart) ---
+UPDATE=""
+UPD_FILE="${XDG_CACHE_HOME:-$HOME/.cache}/trailhead/update-check.json"
+if [ -f "$UPD_FILE" ]; then
+  UPD_AV="$(jq -r '.updateAvailable // false' "$UPD_FILE" 2>/dev/null)"
+  if [ "$UPD_AV" = "true" ]; then
+    UPD_LATEST="$(jq -r '.latest // empty' "$UPD_FILE" 2>/dev/null)"
+    [ -n "$UPD_LATEST" ] && UPDATE="⬆ trailhead ${UPD_LATEST}"
+  fi
+fi
+
+SEP="${C_SEP} | ${C_RST}"
+
+# riga 1: modello | progetto | branch | usage | contesto | (update disponibile)
+OUT="${C_MODEL}${MODEL}${C_RST}"
+[ -n "$PROJ" ]   && OUT="${OUT}${SEP}${C_PROJ}${PROJ}${C_RST}"
+[ -n "$BRANCH" ] && OUT="${OUT}${SEP}${C_BRANCH}${BRANCH}${C_RST}"
+[ -n "$USAGE" ]  && OUT="${OUT}${SEP}${USAGE}"
+[ -n "$CTX" ]    && OUT="${OUT}${SEP}${C_CTX}${CTX}${C_RST}"
+[ -n "$UPDATE" ] && OUT="${OUT}${SEP}${C_UPDATE}${UPDATE}${C_RST}"
+printf '%s\n' "$OUT"
+
+# riga 2: ticket / operazione trailhead in corso (solo se presente)
+if [ -n "$TICKET" ]; then
+  # larghezza terminale, per non far wrappare la riga 2 (STATUSLINE_COLS la forza).
+  # Un valore assente/0/troppo piccolo e' considerato "sconosciuto" -> provo il metodo dopo.
+  valid_cols() { case "$1" in ''|*[!0-9]*) return 1 ;; esac; [ "$1" -ge 10 ]; }
+  COLS="${STATUSLINE_COLS:-${COLUMNS:-}}"
+  valid_cols "$COLS" || COLS="$(tput cols 2>/dev/null)"
+  valid_cols "$COLS" || COLS="$(stty size 2>/dev/null </dev/tty | awk '{print $2}')"
+  valid_cols "$COLS" || COLS=0
+  L2="▸ ${TICKET}"
+  # taglio a COLS-1 (margine per emoji a doppia cella), aggiungendo l'ellissi
+  if [ "$COLS" -gt 3 ] 2>/dev/null && [ "${#L2}" -gt "$((COLS-1))" ]; then
+    L2="${L2:0:$((COLS-2))}…"
+  fi
+  printf '%s\n' "${C_TICKET}${L2}${C_RST}"
+fi
+
+# exit 0 sempre: Claude Code scarta l'output della statusline se l'exit non e' 0
+exit 0

package/plugins/trailhead/templates/trailhead-label-guard.yml

@@ -1,4 +1,4 @@
-# trailhead label guard — repo-side enforcement.
+# 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
@@ -51,5 +51,5 @@ jobs:
             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.`,
+              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(() => {});