@marcomigozzi/trailhead 0.9.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marcomigozzi/trailhead",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Start and drive large projects as a map of tickets on GitHub Issues. Map-based onboarding + a discuss→plan→execute→verify engine, all on the Issues. Installs the trailhead skill, commands, and hooks into your agent's config dir.",
   "bin": {
     "trailhead": "bin/trailhead.js"

package/plugins/trailhead/.claude-plugin/plugin.json

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

package/plugins/trailhead/commands/quick.md

@@ -1,5 +1,5 @@
 ---
-description: Work one ticket whole, off the map (whiteboard); grills only if needed, never splits
+description: Work one ticket whole, never splits: a new whiteboard ticket from text, or an existing one; grills only if needed
 argument-hint: "[ticket | \"text\"]"
 ---
 

package/plugins/trailhead/hooks/lib/commit-message-check.js

@@ -5,13 +5,18 @@
 //   - templates/trailhead-commit-msg    (host-independent git commit-msg hook,
 //     installed into .git/hooks at repo first-use so it runs on ANY host)
 // Two rules: NEVER a Co-Authored-By trailer; a Conventional Commits subject
-// (<type>(scope)?: subject) of at most 72 chars.
+// (<type>(scope)?: subject) of at most 72 chars. Plus a conditional third rule:
+// while a ticket is active (a caller passes opts.ticket, resolved from the
+// .trailhead/session-ticket marker), the message must carry a matching
+// `Refs: #<n>` trailer, so every commit made while resolving a ticket threads
+// into that ticket's timeline.
 // Pure and dependency-free: takes a commit message string, returns a verdict.
 
 const TYPES = 'feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert';
 const CONVENTIONAL = new RegExp(`^(${TYPES})(\\([^)]+\\))?!?:\\s.+`);
 const CO_AUTHORED = /co-authored-by\s*:/i;
 const SCISSORS = '# ------------------------ >8';
+const REFS_LINE = /^\s*refs\s*:(.*)$/i;
 
 // The message region: everything before git's --verbose scissors line (the
 // block after it is the diff, not the message). Everything else is kept, so a
@@ -39,11 +44,46 @@ function subjectOf(raw, opts = {}) {
   return '';
 }
 
+// parseSessionTicket(text) -> ticket number | null
+// Parses the first line of a .trailhead/session-ticket marker (`#<n> <title>`).
+// Strips a leading BOM and any trailing \r before matching, so a marker read
+// with either line-ending convention parses the same way. Anything else
+// (empty text, no leading '#', a non-digit, a leading zero, or trailing
+// characters glued to the digits) is not a valid marker and yields null.
+function parseSessionTicket(text) {
+  const raw = String(text == null ? '' : text).replace(/^/, '');
+  const firstLine = raw.split('\n')[0].replace(/\r$/, '');
+  const m = firstLine.match(/^#([1-9]\d*)(?:\s|$)/);
+  return m ? Number(m[1]) : null;
+}
+
+// hasRefsFor(message, n) -> boolean
+// Scans the message region (see messageRegion) for a `Refs:` trailer line
+// whose value contains `#<n>` not immediately followed by another word
+// character (so `#184` matches but `#18` and `#184abc` do not). A `#`-leading
+// line never counts: it is a git comment in a commit-msg file, and a
+// `# Refs: ...` line is not a trailer in a literal `-m` string either.
+function hasRefsFor(message, n) {
+  const target = new RegExp('#' + n + '(?![\\w])');
+  for (const line of messageRegion(message).split('\n')) {
+    if (line.trim().startsWith('#')) continue;
+    const m = line.match(REFS_LINE);
+    if (m && target.test(m[1])) return true;
+  }
+  return false;
+}
+
 // checkCommitMessage(message, opts?) -> { ok: true } | { ok: false, code, reason }
 // opts.stripComments is forwarded to subjectOf (see there): the git commit-msg
 // hook uses the default (file semantics); the PreToolUse `-m` guard passes false.
+// opts.ticket activates the Refs rule when it is a positive integer (the
+// ticket resolved from a live .trailhead/session-ticket marker); any other
+// value (undefined, a non-integer, a string, 0, negative) leaves the rule off,
+// it never blocks by mistake. When active it applies even to an empty
+// message, closing a `--allow-empty-message` bypass.
 function checkCommitMessage(message, opts = {}) {
   const region = messageRegion(message);
+  const ticketActive = Number.isInteger(opts.ticket) && opts.ticket > 0;
 
   if (CO_AUTHORED.test(region)) {
     return {
@@ -68,7 +108,23 @@ function checkCommitMessage(message, opts = {}) {
       reason: 'trailhead: commit subject must be 72 characters or less.',
     };
   }
+  if (ticketActive && !hasRefsFor(message, opts.ticket)) {
+    return {
+      ok: false,
+      code: 'REFS_TRAILER_MISSING',
+      reason: `trailhead: this commit is on ticket #${opts.ticket} (per .trailhead/session-ticket) but has no "Refs: #${opts.ticket}" trailer. Add "Refs: #${opts.ticket}" as the last line of the message and commit again. If this commit is not part of ticket #${opts.ticket}, remove the stale .trailhead/session-ticket marker first.`,
+    };
+  }
   return { ok: true };
 }
 
-module.exports = { checkCommitMessage, subjectOf, messageRegion, TYPES, CONVENTIONAL, CO_AUTHORED };
+module.exports = {
+  checkCommitMessage,
+  subjectOf,
+  messageRegion,
+  parseSessionTicket,
+  hasRefsFor,
+  TYPES,
+  CONVENTIONAL,
+  CO_AUTHORED,
+};

package/plugins/trailhead/hooks/lib/commit-message-check.test.js

@@ -5,7 +5,9 @@
 // Drives the SAME fixtures through two paths:
 //   1. checkCommitMessage() directly (the source of truth).
 //   2. the template hook (templates/trailhead-commit-msg) end-to-end via
-//      execFileSync, feeding it the message as a temp file.
+//      execFileSync, feeding it the message as a temp file, run from a fresh
+//      mkdtemp cwd (so the template's own .trailhead/session-ticket lookup is
+//      independent of this repo's real marker).
 // The two verdicts must always agree: that agreement is the anti-drift
 // guarantee that keeps the Claude Code hook and the git commit-msg hook from
 // ever diverging.
@@ -15,7 +17,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 
-const { checkCommitMessage } = require('./commit-message-check.js');
+const { checkCommitMessage, parseSessionTicket, hasRefsFor } = require('./commit-message-check.js');
 
 const templatePath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg');
 
@@ -37,7 +39,7 @@ const FIXTURES = [
   { name: 'empty message', message: '', expectOk: true },
 ];
 
-// --- unit: checkCommitMessage() directly ---
+// --- unit: checkCommitMessage() directly (no ticket, no marker) ---
 for (const f of FIXTURES) {
   const verdict = checkCommitMessage(f.message);
   ok(`checkCommitMessage: ${f.name} -> ok=${f.expectOk}`, verdict.ok === f.expectOk);
@@ -46,22 +48,30 @@ for (const f of FIXTURES) {
   }
 }
 
-// --- end-to-end: drive the template hook on the SAME fixtures ---
-function runTemplateHook(message) {
-  const tmpFile = path.join(os.tmpdir(), `trailhead-commit-msg-test-${process.pid}-${Math.random().toString(36).slice(2)}.txt`);
+// --- end-to-end: drive the template hook on the SAME fixtures, no marker ---
+function runTemplateHook(message, marker) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-commit-msg-test-'));
+  const tmpFile = path.join(tmp, 'COMMIT_EDITMSG');
   fs.writeFileSync(tmpFile, message);
+  if (marker !== undefined) {
+    fs.mkdirSync(path.join(tmp, '.trailhead'));
+    fs.writeFileSync(path.join(tmp, '.trailhead', 'session-ticket'), marker);
+  }
+  let allowed = true;
+  let stderr = '';
   try {
-    execFileSync('node', [templatePath, tmpFile]);
-    return true; // exit 0 -> allow
-  } catch {
-    return false; // non-zero exit -> block
+    execFileSync('node', [templatePath, tmpFile], { cwd: tmp, stdio: 'pipe' });
+  } catch (e) {
+    allowed = false;
+    stderr = e.stderr ? e.stderr.toString() : '';
   } finally {
-    fs.rmSync(tmpFile, { force: true });
+    fs.rmSync(tmp, { recursive: true, force: true });
   }
+  return { allowed, stderr };
 }
 
 for (const f of FIXTURES) {
-  const allowed = runTemplateHook(f.message);
+  const { allowed } = runTemplateHook(f.message);
   const expected = checkCommitMessage(f.message).ok;
   ok(`template hook: ${f.name} -> allowed=${expected}`, allowed === expected);
 }
@@ -78,6 +88,86 @@ ok('no-strip: #-leading subject blocks with the conventional code',
 ok('default strip: #-leading line is a comment -> empty subject -> allow',
   checkCommitMessage(hashSubject).ok === true);
 ok('template hook: #-leading message is file-semantics (comment) -> allow',
-  runTemplateHook(hashSubject) === true);
+  runTemplateHook(hashSubject).allowed === true);
+
+// --- parseSessionTicket unit cases ---
+ok('parseSessionTicket: normal marker', parseSessionTicket('#184 Enforce the Refs trailer\n') === 184);
+ok('parseSessionTicket: number only', parseSessionTicket('#184') === 184);
+ok('parseSessionTicket: empty text', parseSessionTicket('') === null);
+ok('parseSessionTicket: missing hash', parseSessionTicket('184 Title') === null);
+ok('parseSessionTicket: non-numeric', parseSessionTicket('#abc') === null);
+ok('parseSessionTicket: zero', parseSessionTicket('#0 Title') === null);
+ok('parseSessionTicket: trailing junk glued to number', parseSessionTicket('#184x Title') === null);
+ok('parseSessionTicket: BOM stripped', parseSessionTicket('#184 Title') === 184);
+ok('parseSessionTicket: CRLF stripped', parseSessionTicket('#184 Title\r\nsecond line') === 184);
+
+// --- Refs / ticket fixtures: [marker, message, expectOk, expectCode?] ---
+const REFS_FIXTURES = [
+  { name: 'refs matches marker', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #184', expectOk: true },
+  { name: 'refs multi list matches', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #12, #184', expectOk: true },
+  { name: 'lowercase refs matches', marker: '#184 Title\n', message: 'feat: x\n\nrefs: #184', expectOk: true },
+  { name: 'no refs at all', marker: '#184 Title\n', message: 'feat: x', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs wrong ticket', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #183', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs prefix-only mismatch (18 vs 184)', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #18', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'marker itself truncated (#18) with refs #184', marker: '#18 Title\n', message: 'feat: x\n\nRefs: #184', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs suffix junk rejected (#184abc)', marker: '#184 Title\n', message: 'feat: x\n\nRefs: #184abc', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'refs only inside a comment line', marker: '#184 Title\n', message: 'feat: x\n\n# Refs: #184', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  {
+    name: 'refs only after the scissors line',
+    marker: '#184 Title\n',
+    message: 'feat: x\n\n# ------------------------ >8 ------------------------\nRefs: #184',
+    expectOk: false,
+    code: 'REFS_TRAILER_MISSING',
+  },
+  { name: 'empty message with active marker still requires refs', marker: '#184 Title\n', message: '', expectOk: false, code: 'REFS_TRAILER_MISSING' },
+  { name: 'no marker: refs rule off, plain conventional commit ok', marker: undefined, message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (no hash): rule off', marker: '184 Title\n', message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (non-numeric): rule off', marker: '#abc\n', message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (empty file): rule off', marker: '', message: 'feat: x', expectOk: true },
+  { name: 'malformed marker (#0): rule off', marker: '#0 Title\n', message: 'feat: x', expectOk: true },
+  {
+    name: 'precedence: non-conventional subject without refs -> conventional code wins',
+    marker: '#184 Title\n',
+    message: 'wip stuff',
+    expectOk: false,
+    code: 'CONVENTIONAL_COMMITS_VIOLATION',
+  },
+];
+
+for (const f of REFS_FIXTURES) {
+  const ticket = parseSessionTicket(f.marker === undefined ? '' : f.marker);
+  const verdict = checkCommitMessage(f.message, { ticket });
+  ok(`checkCommitMessage(ticket): ${f.name} -> ok=${f.expectOk}`, verdict.ok === f.expectOk);
+  if (!f.expectOk && f.code) {
+    ok(`checkCommitMessage(ticket): ${f.name} -> code=${f.code}`, verdict.code === f.code);
+  }
+
+  const { allowed, stderr } = runTemplateHook(f.message, f.marker);
+  ok(`template hook(ticket): ${f.name} -> allowed=${f.expectOk}`, allowed === f.expectOk);
+  if (!f.expectOk && f.code === 'REFS_TRAILER_MISSING') {
+    ok(`template hook(ticket): ${f.name} -> stderr matches lib reason`,
+      stderr.trim() === verdict.reason);
+  }
+}
+
+// --- extra API asserts from the plan ---
+ok('checkCommitMessage: string ticket disables the rule (never blocks)',
+  checkCommitMessage('feat: x', { ticket: '184' }).ok === true);
+ok('checkCommitMessage: numeric ticket + stripComments:false still finds Refs',
+  checkCommitMessage('feat: x\n\nRefs: #184', { ticket: 184, stripComments: false }).ok === true);
+
+// --- template stderr content check for the missing-refs case ---
+{
+  const { stderr } = runTemplateHook('feat: x', '#184 Title\n');
+  ok('template stderr mentions Refs: #184', stderr.includes('Refs: #184'));
+}
+
+// --- hasRefsFor unit checks ---
+ok('hasRefsFor: direct match', hasRefsFor('Refs: #184', 184) === true);
+ok('hasRefsFor: no match', hasRefsFor('Refs: #18', 184) === false);
+ok('hasRefsFor: a "# Refs:" comment line never counts',
+  hasRefsFor('# Refs: #184', 184) === false);
+ok('hasRefsFor: a Refs line in a multi-line body counts',
+  hasRefsFor('feat: x\n\nbody\n\nRefs: #184', 184) === true);
 
 console.log(`✓ commit-message-check: ${passed} assertions passed`);

package/plugins/trailhead/hooks/lib/commit-msg-sync.test.js

@@ -0,0 +1,375 @@
+#!/usr/bin/env node
+// Tests for templates/trailhead-commit-msg-sync.js. Run: node commit-msg-sync.test.js
+// No framework: plain asserts, mirrors the style of commit-message-check.test.js.
+//
+// Covers three layers:
+//   1. isTrailheadHook() / normalize() unit cases.
+//   2. syncCommitMsgHook() unit cases against mkdtemp hook dirs (fs seam left
+//      as the real fs; each case gets its own scratch dir).
+//   3. resolveHooksTarget() with a stubbed runGit (no shelling out).
+//   4. End-to-end: execFileSync the script itself against real git repos.
+const assert = require('assert');
+const { execFileSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+const os = require('os');
+
+const scriptPath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg-sync.js');
+const templatePath = path.resolve(__dirname, '..', '..', 'templates', 'trailhead-commit-msg');
+const oldFixturePath = path.join(__dirname, 'fixtures', 'commit-msg-a319156');
+
+const {
+  resolveHooksTarget,
+  isTrailheadHook,
+  normalize,
+  syncCommitMsgHook,
+} = require(scriptPath);
+
+let passed = 0;
+const ok = (name, cond) => { assert.ok(cond, name); passed++; };
+
+const templateText = fs.readFileSync(templatePath, 'utf8');
+const oldHookText = fs.readFileSync(oldFixturePath, 'utf8');
+
+function mktmp() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'trailhead-commit-msg-sync-test-'));
+}
+
+// --- isTrailheadHook() unit cases -------------------------------------------
+ok('isTrailheadHook: current template is recognised', isTrailheadHook(templateText));
+ok('isTrailheadHook: old (a319156) hook is recognised', isTrailheadHook(oldHookText));
+ok('isTrailheadHook: plain foreign script is not', !isTrailheadHook('#!/bin/sh\necho hi\n'));
+ok('isTrailheadHook: mention outside the first 5 lines, not line-start, is not',
+  !isTrailheadHook('#!/bin/sh\necho hi\necho more\necho stuff\necho again\n# trailhead commit-msg hook (git). fake\n'));
+ok('isTrailheadHook: mention inside an echo on line 2 is not',
+  !isTrailheadHook('#!/bin/sh\necho "trailhead commit-msg hook (git)."\n'));
+ok('isTrailheadHook: empty text is not', !isTrailheadHook(''));
+
+// --- normalize() unit cases --------------------------------------------------
+ok('normalize: CRLF becomes LF', normalize('a\r\nb\r\n') === 'a\nb\n');
+ok('normalize: LF-only text is unchanged', normalize('a\nb\n') === 'a\nb\n');
+
+// --- syncCommitMsgHook() unit cases ------------------------------------------
+function modeOf(p) { return fs.statSync(p).mode & 0o777; }
+
+// absent -> installed, 0755
+{
+  const dir = mktmp();
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  const hookPath = path.join(dir, 'commit-msg');
+  ok('syncCommitMsgHook: absent -> installed', result.status === 'installed');
+  ok('syncCommitMsgHook: absent -> hook path returned', result.hook === hookPath);
+  ok('syncCommitMsgHook: absent -> file written', fs.existsSync(hookPath));
+  ok('syncCommitMsgHook: absent -> content matches template', fs.readFileSync(hookPath, 'utf8') === templateText);
+  ok('syncCommitMsgHook: absent -> mode 0755', modeOf(hookPath) === 0o755);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// old -> upgraded, bytes === template, 0755
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, oldHookText);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: old -> upgraded', result.status === 'upgraded');
+  ok('syncCommitMsgHook: old -> bytes now match template', fs.readFileSync(hookPath, 'utf8') === templateText);
+  ok('syncCommitMsgHook: old -> mode 0755', modeOf(hookPath) === 0o755);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// CRLF current -> current, untouched
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const crlfTemplate = templateText.replace(/\n/g, '\r\n');
+  fs.writeFileSync(hookPath, crlfTemplate);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: CRLF current -> current', result.status === 'current');
+  ok('syncCommitMsgHook: CRLF current -> untouched bytes', fs.readFileSync(hookPath, 'utf8') === crlfTemplate);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// current but mode 0644 -> current, mode fixed to 0755
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  fs.writeFileSync(hookPath, templateText);
+  fs.chmodSync(hookPath, 0o644);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: current 0644 -> status current', result.status === 'current');
+  ok('syncCommitMsgHook: current 0644 -> mode fixed to 0755', modeOf(hookPath) === 0o755);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// foreign shell script -> foreign, untouched
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const foreign = '#!/bin/sh\necho hi\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: foreign shell -> foreign', result.status === 'foreign');
+  ok('syncCommitMsgHook: foreign shell -> bytes untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
+  ok('syncCommitMsgHook: foreign shell -> mode untouched', modeOf(hookPath) === 0o755);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// foreign wrapper mentioning the phrase in an echo on line 2 -> foreign
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const foreign = '#!/bin/sh\necho "trailhead commit-msg hook (git). not really"\nexit 0\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: foreign wrapper mentioning phrase -> foreign', result.status === 'foreign');
+  ok('syncCommitMsgHook: foreign wrapper -> bytes untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// symlink -> foreign, target untouched
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const targetPath = path.join(dir, 'real-hook.sh');
+  const targetContent = '#!/bin/sh\necho real\n';
+  fs.writeFileSync(targetPath, targetContent);
+  fs.symlinkSync(targetPath, hookPath);
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: false, fs });
+  ok('syncCommitMsgHook: symlink -> foreign', result.status === 'foreign');
+  ok('syncCommitMsgHook: symlink -> still a symlink', fs.lstatSync(hookPath).isSymbolicLink());
+  ok('syncCommitMsgHook: symlink target untouched', fs.readFileSync(targetPath, 'utf8') === targetContent);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// absent + hooksPathSet -> skipped, nothing created
+{
+  const dir = mktmp();
+  const hookPath = path.join(dir, 'commit-msg');
+  const result = syncCommitMsgHook({ hooksDir: dir, templateText, hooksPathSet: true, fs });
+  ok('syncCommitMsgHook: absent + hooksPathSet -> skipped', result.status === 'skipped');
+  ok('syncCommitMsgHook: absent + hooksPathSet -> nothing created', !fs.existsSync(hookPath));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --- resolveHooksTarget() with a stubbed runGit ------------------------------
+{
+  const stubThrow = () => { throw new Error('not a git repo'); };
+  const result = resolveHooksTarget({ repoDir: '/nonexistent-repo-dir', runGit: stubThrow });
+  ok('resolveHooksTarget: no-repo -> skip', result.skip === 'no-repo');
+}
+{
+  let calls = 0;
+  const runGit = (args) => {
+    calls++;
+    if (args[0] === 'rev-parse' && args[1] === '--git-dir') return '.git';
+    if (args[0] === 'rev-parse' && args[1] === '--git-path') return '.git/hooks';
+    if (args[0] === 'config') throw new Error('not set');
+    throw new Error('unexpected args: ' + args.join(' '));
+  };
+  const result = resolveHooksTarget({ repoDir: '/some/repo', runGit });
+  ok('resolveHooksTarget: hooksDir resolved against repoDir', result.hooksDir === path.resolve('/some/repo', '.git/hooks'));
+  ok('resolveHooksTarget: hooksPathSet false when core.hooksPath unset', result.hooksPathSet === false);
+  ok('resolveHooksTarget: runGit called', calls >= 2);
+}
+{
+  const runGit = (args) => {
+    if (args[0] === 'rev-parse' && args[1] === '--git-dir') return '.git';
+    if (args[0] === 'rev-parse' && args[1] === '--git-path') return '.git/hooks';
+    if (args[0] === 'config') return '.githooks';
+    throw new Error('unexpected args: ' + args.join(' '));
+  };
+  const result = resolveHooksTarget({ repoDir: '/some/repo', runGit });
+  ok('resolveHooksTarget: hooksPathSet true when core.hooksPath set', result.hooksPathSet === true);
+}
+
+console.log(`✓ commit-msg-sync (unit): ${passed} assertions passed`);
+
+// --- end-to-end: drive the script itself against real git repos -------------
+function gitEnv(extra) {
+  return Object.assign({}, process.env, {
+    GIT_CONFIG_GLOBAL: '/dev/null',
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_AUTHOR_NAME: 'Trailhead Test',
+    GIT_AUTHOR_EMAIL: 'trailhead-test@example.com',
+    GIT_COMMITTER_NAME: 'Trailhead Test',
+    GIT_COMMITTER_EMAIL: 'trailhead-test@example.com',
+  }, extra || {});
+}
+
+function runScript(args, opts) {
+  const out = execFileSync(process.execPath, [scriptPath].concat(args), Object.assign({ encoding: 'utf8' }, opts));
+  return out;
+}
+
+function assertSingleJsonLine(out, label) {
+  const lines = out.split('\n').filter((l) => l.length > 0);
+  ok(`${label}: stdout is exactly one line`, lines.length === 1);
+  let parsed;
+  assert.doesNotThrow(() => { parsed = JSON.parse(lines[0]); }, `${label}: stdout line is valid JSON`);
+  passed++;
+  ok(`${label}: JSON has exactly [status, hook, message] keys`,
+    Object.keys(parsed).sort().join(',') === 'hook,message,status');
+  return parsed;
+}
+
+// fresh repo: installed, then current on a second run
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  const out1 = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed1 = assertSingleJsonLine(out1, 'e2e fresh repo (1st run)');
+  ok('e2e fresh repo: status installed', parsed1.status === 'installed');
+  const hookPath = path.join(dir, '.git', 'hooks', 'commit-msg');
+  ok('e2e fresh repo: hook file exists', fs.existsSync(hookPath));
+  ok('e2e fresh repo: hook is executable', (modeOf(hookPath) & 0o111) !== 0);
+
+  const out2 = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed2 = assertSingleJsonLine(out2, 'e2e fresh repo (2nd run)');
+  ok('e2e fresh repo (2nd run): status current', parsed2.status === 'current');
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// seeded old hook -> upgraded
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  const hooksDir = path.join(dir, '.git', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, 'commit-msg');
+  fs.writeFileSync(hookPath, oldHookText);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e seeded old hook');
+  ok('e2e seeded old hook: status upgraded', parsed.status === 'upgraded');
+  ok('e2e seeded old hook: content now matches template', fs.readFileSync(hookPath, 'utf8') === templateText);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// seeded foreign hook -> untouched
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  const hooksDir = path.join(dir, '.git', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, 'commit-msg');
+  const foreign = '#!/bin/sh\necho "custom hook"\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e seeded foreign hook');
+  ok('e2e seeded foreign hook: status foreign', parsed.status === 'foreign');
+  ok('e2e seeded foreign hook: bytes untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// core.hooksPath = .githooks, absent -> skipped, nothing created anywhere
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: dir, env: gitEnv() });
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e core.hooksPath absent');
+  ok('e2e core.hooksPath absent: status skipped', parsed.status === 'skipped');
+  ok('e2e core.hooksPath absent: .githooks/commit-msg not created', !fs.existsSync(path.join(dir, '.githooks', 'commit-msg')));
+  ok('e2e core.hooksPath absent: .git/hooks/commit-msg not created', !fs.existsSync(path.join(dir, '.git', 'hooks', 'commit-msg')));
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// core.hooksPath = .githooks, old hook there -> upgraded there
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: dir, env: gitEnv() });
+  const githooksDir = path.join(dir, '.githooks');
+  fs.mkdirSync(githooksDir, { recursive: true });
+  const hookPath = path.join(githooksDir, 'commit-msg');
+  fs.writeFileSync(hookPath, oldHookText);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e core.hooksPath old hook');
+  ok('e2e core.hooksPath old hook: status upgraded', parsed.status === 'upgraded');
+  ok('e2e core.hooksPath old hook: upgraded in .githooks', fs.readFileSync(hookPath, 'utf8') === templateText);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// core.hooksPath = .githooks, foreign hook there -> untouched
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['config', 'core.hooksPath', '.githooks'], { cwd: dir, env: gitEnv() });
+  const githooksDir = path.join(dir, '.githooks');
+  fs.mkdirSync(githooksDir, { recursive: true });
+  const hookPath = path.join(githooksDir, 'commit-msg');
+  const foreign = '#!/bin/sh\necho "custom"\n';
+  fs.writeFileSync(hookPath, foreign);
+  fs.chmodSync(hookPath, 0o755);
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e core.hooksPath foreign hook');
+  ok('e2e core.hooksPath foreign hook: status foreign', parsed.status === 'foreign');
+  ok('e2e core.hooksPath foreign hook: untouched', fs.readFileSync(hookPath, 'utf8') === foreign);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// linked worktree -> hook lands in the main repo's .git/hooks
+{
+  const dir = mktmp();
+  execFileSync('git', ['init', '-q'], { cwd: dir, env: gitEnv() });
+  execFileSync('git', ['-c', 'user.name=t', '-c', 'user.email=t@t',
+    'commit', '--allow-empty', '-m', 'chore: init', '--no-verify'], { cwd: dir, env: gitEnv() });
+  const worktreeDir = path.join(dir, '..', path.basename(dir) + '-wt');
+  execFileSync('git', ['worktree', 'add', worktreeDir, '-b', 'trailhead-wt'], { cwd: dir, env: gitEnv(), stdio: 'pipe' });
+  try {
+    const out = runScript(['--repo', worktreeDir], { env: gitEnv() });
+    const parsed = assertSingleJsonLine(out, 'e2e linked worktree');
+    ok('e2e linked worktree: status installed', parsed.status === 'installed');
+    const mainHookPath = path.join(dir, '.git', 'hooks', 'commit-msg');
+    ok('e2e linked worktree: hook lands in the main repo .git/hooks', fs.existsSync(mainHookPath));
+    ok('e2e linked worktree: reported hook path is the main repo one', parsed.hook === mainHookPath);
+  } finally {
+    try { execFileSync('git', ['worktree', 'remove', '--force', worktreeDir], { cwd: dir, env: gitEnv(), stdio: 'pipe' }); } catch { /* best effort cleanup */ }
+    fs.rmSync(worktreeDir, { recursive: true, force: true });
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+// non-repo tmp dir -> skipped, exit 0
+{
+  const dir = mktmp();
+  const out = runScript(['--repo', dir], { env: gitEnv() });
+  const parsed = assertSingleJsonLine(out, 'e2e non-repo dir');
+  ok('e2e non-repo dir: status skipped', parsed.status === 'skipped');
+  ok('e2e non-repo dir: hook is null', parsed.hook === null);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --bogus -> exit 2
+{
+  const dir = mktmp();
+  let exitCode = null;
+  try {
+    execFileSync(process.execPath, [scriptPath, '--bogus'], { cwd: dir, env: gitEnv(), stdio: 'pipe' });
+  } catch (e) {
+    exitCode = e.status;
+  }
+  ok('e2e --bogus: exits 2', exitCode === 2);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// --repo without a value -> exit 2
+{
+  const dir = mktmp();
+  let exitCode = null;
+  try {
+    execFileSync(process.execPath, [scriptPath, '--repo'], { cwd: dir, env: gitEnv(), stdio: 'pipe' });
+  } catch (e) {
+    exitCode = e.status;
+  }
+  ok('e2e --repo without value: exits 2', exitCode === 2);
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+console.log(`✓ commit-msg-sync (e2e): ${passed} assertions passed`);