@marcomigozzi/trailhead 0.12.0 → 0.12.1

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.12.1",
   "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.12.1",
   "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/skills/_shared/load-first.md

@@ -18,3 +18,5 @@ Before doing anything, read the shared core, in order:
 Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file), before any isolation workspace is set up.
 
 **Pinned model review, once per session.** After loading the effective config, run the read-only check: `node <lib> check <project root>`, where `<lib>` is the first of these two paths (relative to this `_shared/` dir) that exists: `../../hooks/lib/model-defaults-review.js` (Claude plugin, Claude npm copy, dev-symlink install), else `../trailhead/hooks/lib/model-defaults-review.js` (Codex). If neither exists, skip silently. If it prints a notice, offer it to the user without blocking the current request; only after the user answers any of its three choices, run `node <lib> ack <project root>`. Do this at most once per session: skip it if the SessionStart hook (or an earlier config load this session) already surfaced the same offer. Repeats across sessions are expected until the user answers.
+
+**Label guard check, once per session.** Same pattern for the repo's label guard: run `node <templates>/trailhead-label-guard-sync.js --repo <project root> --notice`, with `<templates>` resolved as for the commit-msg sync script (see `teamwork.md`, Trust & provenance → Repo-side enforcement; skip silently if none of the template dirs has the script). It prints an offer only when the committed guard is the outdated one (no job-level `if:`, so every label event bills a runner) and the user has not answered for that file yet. Offer it without blocking the current request and follow its instructions; only after the user picks either choice, run the `--ack` command it names. At most once per session: skip it if the SessionStart hook already surfaced it.

package/plugins/trailhead/skills/_shared/substrate-commands.md

@@ -200,5 +200,5 @@ gh api repos/{owner}/{repo}/issues/<map> --jq '.sub_issues_summary.total'
 
 ## First-use repo setup (do ALL THREE, every chart or adopt, never skip any)
 1. Create any missing labels with `gh label create` (all eighteen: `trailhead:map`, `trailhead:codebase`, `trailhead:conventions`, `trailhead:dashboard`, `trailhead:ticket`, the six type labels, `trailhead:blocked`, `trailhead:seed`, `trailhead:out-of-scope`, `trailhead:superseded`, `trailhead:unverified`, `trailhead:fog`, `trailhead:whiteboard`).
-2. **Check the label guard is installed**: `gh api repos/{owner}/{repo}/contents/.github/workflows/trailhead-label-guard.yml`; if it's absent (404), install it: **read `teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. This is part of standing up trailhead in a repo, not an optional extra: *check every time*, so a repo can never end up with the labels but no guard.
+2. **Check the label guard is installed and current**: `gh api repos/{owner}/{repo}/contents/.github/workflows/trailhead-label-guard.yml`; if it's absent (404), install it; if it's present, run the label guard sync script (`trailhead-label-guard-sync.js`, check-only) on the working root and, when it reports `outdated` (a pre-0.12.1 guard with no job-level `if:`, which starts a billed runner on every `issues: labeled` event), offer the upgrade: **read `teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. This is part of standing up trailhead in a repo, not an optional extra: *check every time*, so a repo can never end up with the labels but no guard, or with a guard that burns Actions minutes.
 3. **Sync the commit-msg git hook**: run the commit-msg hook sync script (`trailhead-commit-msg-sync.js`; installs it if absent, upgrades an outdated trailhead hook in place, never touches a foreign one) so trailhead's commit discipline (Conventional Commits subject, no `Co-Authored-By`, and a `Refs: #<n>` trailer while a `.trailhead/session-ticket` marker is active) runs on **every** `git commit` regardless of host (the Claude-Code `PreToolUse` guard stays too, defence in depth): **read `teamwork.md` (Trust & provenance → Repo-side enforcement) for the exact steps**. If the script is missing or node errors (missing means none of the three template dirs listed in `teamwork.md` has it: try them all first), fall back to inspecting the hooks dir (`git rev-parse --git-path hooks`) per `teamwork.md`, never a blind "not enforced". Like the label guard, *check every time*; unlike it, `.git/hooks/` is per-clone local state (untracked), so it is installed, never committed.

package/plugins/trailhead/skills/_shared/teamwork.md

@@ -94,4 +94,6 @@ The map issue's **body** is a shared mutable document: two sessions appending to
 
 **Repo-side enforcement (part of first-use setup, not an afterthought).** trailhead **installs the label guard for you**; don't tell the user to copy files. **Every chart or adopt, *check* whether `.github/workflows/trailhead-label-guard.yml` exists** (the first-use repo setup, in SKILL.md's Substrate section); if it's absent, install it, by default on a repo with other collaborators, and as a quick offer on a clearly solo/private one (cheap insurance), but **never silently skip the check**: that's exactly how a repo ends up with trailhead labels and no guard. On go-ahead, write the shipped label-guard template (`${CLAUDE_PLUGIN_ROOT}/templates/trailhead-label-guard.yml` for a plugin install, or `~/.claude/trailhead/templates/trailhead-label-guard.yml` for an npm install, take whichever exists) to the repo's `.github/workflows/trailhead-label-guard.yml` and commit it (conventional message; the commit-guard hook keeps it clean). The Action strips any `trailhead:*` label added by a non-write actor and comments why; set an optional `TRAILHEAD_LABEL_ALLOWLIST` repo variable to whitelist extra logins (e.g. a bot trailhead runs as). **Caveat:** pushing a workflow file needs a token with the `workflow` scope; if the push is rejected, run `gh auth refresh -s workflow` and retry (or, as a last resort, tell the user to add the file by hand).
 
+**Keeping the guard current (migration).** The guard filters at **job level** (`jobs.guard.if`: a `trailhead:` label, a sender other than the repo owner, not in `TRAILHEAD_LABEL_ALLOWLIST`), because a skipped job is not billed while a job that starts and returns early from its script costs at least one Actions minute; the in-script permission check stays the real defence. Guards installed before 0.12.1 lack that `if:` and start a runner on **every** label event, which with trailhead labelling all the time runs into thousands of billed runs a month. So whenever the guard is present (every chart/adopt, and after `/trailhead:update`), run `node <templates>/trailhead-label-guard-sync.js --repo <working-root>` (same `<templates>` lookup as the commit-msg sync script below). It prints one JSON status line: `current` (nothing to do), `outdated` (offer the upgrade and always explain why in the question, in plain words: today every label added to an issue starts a run billed at least one minute even when it does nothing, trailhead labels constantly so that adds up to thousands of billed runs a month and can exhaust the Actions minutes, and the updated guard skips irrelevant events before a runner starts with the same protection), `custom` (has the job-level filter but differs from the template: leave it, mention it only if asked), `foreign` (not a trailhead workflow: never touched), `absent` (install as above). On go-ahead for `outdated`, re-run it with `--apply` (it rewrites the file from the template in the working tree only, never a foreign or customised guard), then commit it (`fix: skip trailhead label guard job for irrelevant label events`) and push, with the same `workflow`-scope caveat. The SessionStart hook (or, on a host with no hook bus, the load-first check) also runs it with `--notice` at every session start and surfaces the same upgrade offer until the user answers it; `--ack` records the answer in the gitignored `.trailhead/label-guard-ack` (the guard's hash), so a declined offer comes back only if the file changes. If the script is missing (an outdated install), fall back to reading the file and checking `jobs.guard` for an `if:` containing `startsWith(github.event.label.name, 'trailhead:')`.
+
 **The commit-msg git hook (host-independent commit guard).** On every host trailhead ALSO installs a git **`commit-msg`** hook as a host-independent backstop (defence in depth alongside the host's own `PreToolUse` guard on Claude Code and Codex alike), enforcing the two rules (a Conventional Commits subject of at most 72 chars; never a `Co-Authored-By` trailer) plus, while a `.trailhead/session-ticket` marker is present at the worktree root, a `Refs: #<n>` trailer matching its number, on every `git commit`, whatever host drives it (decision #16). **Every chart or adopt, and at every `work`/`quick` ticket start, run the sync script**: `node <templates>/trailhead-commit-msg-sync.js --repo <working-root>`, where `<templates>` is the first of `${CLAUDE_PLUGIN_ROOT}/templates/`, `~/.claude/trailhead/templates/`, `~/.codex/skills/trailhead/templates/` that contains `trailhead-commit-msg-sync.js`: try all three in order, skipping the first when `CLAUDE_PLUGIN_ROOT` is unset or empty (it is often absent from the Bash environment), and never stop at the first miss. It prints one JSON status line and handles every case itself: absent -> installs it; an older trailhead hook (recognised by its own header line, not by trusting the filename) -> upgraded in place; already current -> left alone; a foreign (non-trailhead) hook -> never touched, only reported (offer to chain it); under a repo's `core.hooksPath`, an existing trailhead hook there is still upgraded in place, but nothing is newly added to that directory. Unlike the label guard, `.git/hooks/` is not version-controlled, so this is a per-clone local install with nothing to commit. **If the sync script is missing (none of the three dirs has it: an outdated install) or node errors, never claim git enforces nothing before looking**: resolve the effective hooks dir with `git -C <working-root> rev-parse --git-path hooks` (resolve a relative output against the working root; it honours `core.hooksPath` and the git common dir shared by linked worktrees), read `<hooks dir>/commit-msg`, and classify it by its header line (a trailhead hook has `// trailhead commit-msg hook (git).` among its first 5 lines, trimmed; never trust the filename alone; a symlinked `commit-msg` counts as foreign, as the script treats it). Report one result-oriented line: (a) trailhead hook present and executable (`test -x`): git does enforce trailhead's rules here, but its freshness could not be checked or upgraded, so suggest updating the trailhead install; a trailhead hook that is NOT executable: git skips it, so it does not enforce trailhead's rules here (suggest updating the install so the sync script can fix the mode); (b) a foreign hook (or a symlink): left untouched, git does not enforce trailhead's rules here; (c) no hook: git does not enforce trailhead's rules here (suggest updating the install so the sync script can install it). Never blocks the work.

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

@@ -51,4 +51,8 @@ After the cache refresh, run a **lightweight integrity check** (fs existence plu
 
 The check is lightweight and degrades silently: a probe that can't run (an unreadable path, a host detail absent) is reported as unchecked, never a hard failure of the update.
 
+## 6. Realign this repo's label guard
+
+An update can change the shipped label guard, but a guard already committed to a repo is not touched by the install. If the current directory is a repo with `.github/workflows/trailhead-label-guard.yml`, run the label guard sync script check-only (see `../../_shared/teamwork.md`, Trust & provenance → Keeping the guard current) and, on `outdated`, offer the upgrade (`--apply`, then commit and push); `current`, `custom` and `foreign` need no action. Skip silently when there is no guard or no repo.
+
 Never edit `package.json`/`plugin.json` versions here: this command **consumes** releases, it does not cut them.

package/plugins/trailhead/templates/trailhead-label-guard-sync.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+'use strict';
+// trailhead label guard sync (self-contained, ships in templates/ so it
+// reaches every install channel). Classifies the repo's
+// .github/workflows/trailhead-label-guard.yml against the sibling template
+// and, with --apply, installs it when absent or upgrades an OUTDATED trailhead
+// guard (one without the job-level `if:` filter, so every `issues: labeled`
+// event started a billed runner). Never touches a foreign or customised guard.
+//
+// CLI: node trailhead-label-guard-sync.js [--repo <dir>] [--apply | --notice | --ack]
+// Default and --apply print exactly one JSON line: {"status","file","message"}.
+// --notice prints the session-start upgrade offer (plain text) when the guard
+// is outdated and the user has not declined it for this exact file, else
+// nothing. --ack records that the user answered the offer: it stores the
+// guard's hash in the gitignored .trailhead/label-guard-ack, so the offer
+// comes back only if the file changes.
+//   status (check):  absent | current | outdated | custom | foreign | skipped
+//   status (--apply): installed | upgraded, or the check status when nothing
+//                     was written
+// Writing only changes the working tree: committing (and pushing, which needs
+// the `workflow` token scope) stays with the caller.
+// Exit 0 on every normal outcome (including unexpected errors: this must never
+// block the caller); exit 2 only on a usage error.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const GUARD_REL = path.join('.github', 'workflows', 'trailhead-label-guard.yml');
+// Prima riga di ogni versione del guard trailhead (tra le prime 5, trim).
+const TRAILHEAD_MARK = '# trailhead label guard:';
+const ACK_REL = path.join('.trailhead', 'label-guard-ack');
+// Il filtro che deve stare nell'`if:` a livello di job.
+const JOB_FILTER = "startsWith(github.event.label.name, 'trailhead:')";
+
+function normalize(text) {
+  return String(text == null ? '' : text).replace(/\r\n/g, '\n');
+}
+
+function isTrailheadGuard(text) {
+  return normalize(text).split('\n').slice(0, 5).some((line) => line.trim().startsWith(TRAILHEAD_MARK));
+}
+
+// Estrae il testo dell'`if:` diretto di jobs.guard (indentazione 4, prima del
+// successivo `steps:`/chiave), incluse le righe di continuazione di `>-`.
+// null se jobs.guard non ha un `if:` a livello di job.
+function jobGuardIf(text) {
+  const lines = normalize(text).split('\n');
+  const start = lines.findIndex((l) => /^ {2}guard:\s*$/.test(l));
+  if (start < 0) return null;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (/^\S/.test(line) || /^ {2}\S/.test(line)) return null; // fine del job
+    const m = /^ {4}if:\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const parts = [m[1]];
+    for (let j = i + 1; j < lines.length && /^ {6,}\S/.test(lines[j]); j++) parts.push(lines[j].trim());
+    return parts.join(' ');
+  }
+  return null;
+}
+
+function hasJobLevelFilter(text) {
+  const cond = jobGuardIf(text);
+  return cond !== null && cond.includes(JOB_FILTER);
+}
+
+function classify({ existingText, templateText }) {
+  if (existingText == null) return 'absent';
+  if (!isTrailheadGuard(existingText)) return 'foreign';
+  if (normalize(existingText) === normalize(templateText)) return 'current';
+  return hasJobLevelFilter(existingText) ? 'custom' : 'outdated';
+}
+
+const MESSAGES = {
+  absent: 'no trailhead label guard in this repo.',
+  current: 'the trailhead label guard is already current.',
+  outdated: 'the trailhead label guard is outdated: no job-level filter, so every label event starts a billed runner.',
+  custom: 'the trailhead label guard has the job-level filter but differs from the template; left untouched.',
+  foreign: 'a non-trailhead workflow sits at the label guard path; left untouched.',
+  installed: 'installed the trailhead label guard (commit it).',
+  upgraded: 'upgraded the trailhead label guard to the current template (commit it).',
+};
+
+function writeAtomic(filePath, text, fsMod) {
+  const dir = path.dirname(filePath);
+  fsMod.mkdirSync(dir, { recursive: true });
+  const tmpPath = path.join(dir, `.trailhead-label-guard-${process.pid}-${crypto.randomBytes(4).toString('hex')}`);
+  try {
+    fsMod.writeFileSync(tmpPath, text);
+    fsMod.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try { fsMod.unlinkSync(tmpPath); } catch { /* best effort cleanup */ }
+    throw err;
+  }
+}
+
+function syncLabelGuard({ repoDir, templateText, apply = false, fs: fsMod = fs }) {
+  const file = path.join(repoDir, GUARD_REL);
+  const existingText = fsMod.existsSync(file) ? fsMod.readFileSync(file, 'utf8') : null;
+  const status = classify({ existingText, templateText });
+  if (apply && (status === 'absent' || status === 'outdated')) {
+    writeAtomic(file, templateText, fsMod);
+    const done = status === 'absent' ? 'installed' : 'upgraded';
+    return { status: done, file, message: MESSAGES[done] };
+  }
+  return { status, file, message: MESSAGES[status] };
+}
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(normalize(text)).digest('hex');
+}
+
+function readGuard(repoDir, fsMod) {
+  const file = path.join(repoDir, GUARD_REL);
+  return fsMod.existsSync(file) ? fsMod.readFileSync(file, 'utf8') : null;
+}
+
+// Registra la risposta all'offerta: hash del guard attuale, cosi' l'offerta
+// torna solo se il file cambia. false se non c'e' un guard da ackare.
+function ackGuard({ repoDir, fs: fsMod = fs }) {
+  const existingText = readGuard(repoDir, fsMod);
+  if (existingText == null) return false;
+  const file = path.join(repoDir, ACK_REL);
+  fsMod.mkdirSync(path.dirname(file), { recursive: true });
+  fsMod.writeFileSync(file, sha256(existingText) + '\n');
+  return true;
+}
+
+function isAcked(repoDir, existingText, fsMod) {
+  try {
+    return fsMod.readFileSync(path.join(repoDir, ACK_REL), 'utf8').trim() === sha256(existingText);
+  } catch {
+    return false;
+  }
+}
+
+// Offerta di sessione (SessionStart o load-first inline): solo per un guard
+// trailhead `outdated` non ancora ackato. Sola lettura, mai eccezioni.
+function sessionNotice({ repoDir, templateText, scriptPath, fs: fsMod = fs }) {
+  try {
+    const existingText = readGuard(repoDir, fsMod);
+    if (classify({ existingText, templateText }) !== 'outdated') return null;
+    if (isAcked(repoDir, existingText, fsMod)) return null;
+    const cmd = `node "${scriptPath}" --repo "${repoDir}"`;
+    return [
+      `trailhead's label guard in this repo (${GUARD_REL}) is outdated: it has no job-level \`if:\`, so every \`issues: labeled\` event starts a GitHub Actions runner billed at least one minute, even for labels it ignores.`,
+      'Offer the user, once, without blocking their current request, two choices, and put the reason in the question itself, in plain words, not just the choices. Say that the workflow currently starts a GitHub Actions run every time any label is added to an issue, that GitHub bills each run at least one minute even when the workflow then does nothing, that trailhead adds labels all the time so this can reach thousands of billed runs a month and use up the Actions minutes, and that the updated version skips irrelevant label events before a runner starts (skipped runs are free) while keeping the same protection.',
+      `1) upgrade it: run \`${cmd} --apply\`, then commit the file (\`fix: skip trailhead label guard job for irrelevant label events\`) and push (a workflow file needs the \`workflow\` token scope: run \`gh auth refresh -s workflow\` if the push is rejected);`,
+      '2) keep it as it is.',
+      `This offer reappears every session until answered: once the user has picked either choice, run: ${cmd} --ack`,
+    ].join('\n');
+  } catch {
+    return null;
+  }
+}
+
+function parseArgs(argv) {
+  let repo = null;
+  let apply = false;
+  let mode = 'sync';
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--repo') {
+      i++;
+      if (i >= argv.length) return { error: 'usage: --repo requires a value' };
+      repo = argv[i];
+    } else if (arg === '--apply') {
+      apply = true;
+    } else if (arg === '--notice' || arg === '--ack') {
+      if (mode !== 'sync') return { error: 'usage: --notice and --ack are exclusive' };
+      mode = arg.slice(2);
+    } else {
+      return { error: `usage: unknown argument: ${arg}` };
+    }
+  }
+  if (apply && mode !== 'sync') return { error: `usage: --apply cannot be combined with --${mode}` };
+  return { repo, apply, mode };
+}
+
+function main(argv, { cwd, stdout } = {}) {
+  const out = stdout || process.stdout;
+  const parsed = parseArgs(argv || []);
+  if (parsed.error) {
+    process.stderr.write(parsed.error + '\n');
+    return 2;
+  }
+  const repoDir = path.resolve(cwd || process.cwd(), parsed.repo || '.');
+  try {
+    const templateText = fs.readFileSync(path.join(__dirname, 'trailhead-label-guard.yml'), 'utf8');
+    if (parsed.mode === 'notice') {
+      const notice = sessionNotice({ repoDir, templateText, scriptPath: __filename });
+      if (notice) out.write(notice + '\n');
+      return 0;
+    }
+    if (parsed.mode === 'ack') {
+      ackGuard({ repoDir });
+      return 0;
+    }
+    out.write(JSON.stringify(syncLabelGuard({ repoDir, templateText, apply: parsed.apply })) + '\n');
+  } catch (err) {
+    if (parsed.mode !== 'sync') return 0; // notice/ack: mai rumore
+    out.write(JSON.stringify({ status: 'skipped', file: path.join(repoDir, GUARD_REL), message: 'error: ' + (err && err.message ? err.message : String(err)) }) + '\n');
+  }
+  return 0;
+}
+
+module.exports = { normalize, isTrailheadGuard, jobGuardIf, hasJobLevelFilter, classify, syncLabelGuard, sessionNotice, ackGuard, parseArgs, main, GUARD_REL, ACK_REL, JOB_FILTER };
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2), { cwd: process.cwd(), stdout: process.stdout }));
+}

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

@@ -18,6 +18,11 @@ permissions:
 
 jobs:
   guard:
+    # Filtro a livello di job: un job saltato non consuma minuti Actions.
+    if: >-
+      startsWith(github.event.label.name, 'trailhead:') &&
+      github.event.sender.login != github.repository_owner &&
+      !contains(format(',{0},', vars.TRAILHEAD_LABEL_ALLOWLIST), format(',{0},', github.event.sender.login))
     runs-on: ubuntu-latest
     steps:
       - uses: actions/github-script@v7