create-byan-agent 2.53.0 → 2.54.0

package/CHANGELOG.md

@@ -9,6 +9,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.54.0] - 2026-07-21
+
+### Added — Garde de fraicheur des skills (SessionStart)
+- Nouveau hook `skill-freshness-check.js` (coeur pur `lib/skill-freshness.js`) :
+  au demarrage de session, compare chaque `.claude/skills/<n>/SKILL.md` du
+  projet avec la copie globale homonyme `~/.claude/skills/<n>/SKILL.md`, par
+  CONTENU (l'egalite d'octets dit "fidele" ; une date recente ne dit rien).
+  En cas de divergence, injecte un signalement borne (6 noms max) avec la
+  commande de synchro exacte. Silencieux quand tout est fidele, quand la copie
+  globale n'existe pas, ou quand le projet n'a pas de skills ; sort en 0 dans
+  tous les chemins (ne bloque pas une session).
+- Ferme le piege constate le 2026-07-21 : une copie globale du 30 juin masquait
+  le skill projet — le rail auto-dispatch livre en 2.53.0 ne se declenchait pas
+  car `/byan-byan` chargeait la copie perimee. Point verifie aupres de la doc
+  officielle Claude Code : la regle de priorite skills user vs projet en cas de
+  collision de nom n'y est pas clairement documentee (le hook signale donc le
+  FAIT de la divergence, sans affirmer une regle de chargement).
+- Aucune ecriture automatique dans `~/.claude/skills` : une variante user-level
+  peut etre deliberee — le hook signale, l'humain tranche.
+- Cablage : enregistre sous SessionStart dans `.claude/settings.json` (repo +
+  template) ; les deux fichiers shippent via le miroir `template-sync.js`.
+
 ## [2.53.0] - 2026-07-21
 
 ### Added — Rail automatique : workflow natif byan-auto-dispatch (F2)

package/install/templates/.claude/hooks/lib/skill-freshness.js

@@ -0,0 +1,83 @@
+'use strict';
+
+// skill-freshness — the pure core of the stale-global-skill guard.
+//
+// The trap this closes (observed 2026-07-21): a manual copy of a skill under
+// ~/.claude/skills/<name>/SKILL.md drifts silently, and the slash command can
+// load THAT copy instead of the project's .claude/skills/<name>/SKILL.md — so a
+// feature shipped in the project skill stays invisible (the 2.53.0 auto-dispatch
+// rail did not fire because of a June 30 global copy). The official Claude Code
+// docs do not clearly settle the name-collision priority between the two levels
+// (checked 2026-07-21), so this guard flags the FACT — the two files differ —
+// and hands the human the exact sync command; it does not claim a loading rule
+// and it never writes into ~/.claude itself (a user-level variant may be
+// deliberate; the human decides).
+//
+// Pure: comparison + decision + message. The I/O shell (SessionStart hook)
+// feeds it directories and prints the reminder.
+
+const fs = require('fs');
+const path = require('path');
+
+// Compare the project's skills with same-named global copies, by CONTENT.
+// A newer mtime does not mean "up to date"; byte equality means "faithful".
+// Returns { diverged: [name...], checked: <count> }; every fs error on one
+// skill is swallowed (that skill is simply not compared) so a permission oddity
+// can never break the caller.
+function compareSkills({ projectSkillsDir, globalSkillsDir }) {
+  const out = { diverged: [], checked: 0 };
+  let names;
+  try {
+    names = fs.readdirSync(projectSkillsDir, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name);
+  } catch {
+    return out; // project has no skills dir -> nothing to compare
+  }
+  for (const name of names) {
+    try {
+      const proj = path.join(projectSkillsDir, name, 'SKILL.md');
+      const glob = path.join(globalSkillsDir, name, 'SKILL.md');
+      if (!fs.existsSync(glob)) continue; // no global twin -> no masking risk
+      const a = fs.readFileSync(proj);
+      const b = fs.readFileSync(glob);
+      out.checked += 1;
+      if (!a.equals(b)) out.diverged.push(name);
+    } catch {
+      // unreadable pair -> skip silently (never block a session start)
+    }
+  }
+  return out;
+}
+
+// Bounded, factual reminder. Empty string when nothing diverged (the hook then
+// prints nothing at all). Names are capped so a badly drifted machine does not
+// flood the context; the sync command is exact and copy-pastable.
+const MAX_NAMES = 6;
+
+// A skill dir name lands verbatim in the injected context and in the suggested
+// cp command. Legit names are kebab-case; strip control chars and whitespace
+// runs from anything else so a crafted dir name cannot shape the reminder.
+function cleanName(n) {
+  return String(n).replace(/[\u0000-\u001F\u007F]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function formatReminder(diverged, { projectSkillsDir = '.claude/skills', globalSkillsDir = '~/.claude/skills' } = {}) {
+  if (!Array.isArray(diverged) || diverged.length === 0) return '';
+  const names = diverged.map(cleanName);
+  const shown = names.slice(0, MAX_NAMES).join(', ');
+  const more = names.length > MAX_NAMES ? ` (+${names.length - MAX_NAMES} autres)` : '';
+  const one = names[0];
+  return [
+    `Skills globaux divergents detectes : ${shown}${more}.`,
+    `La copie ${globalSkillsDir}/<nom>/SKILL.md differe du skill projet — elle peut etre celle que la commande /<nom> charge (constate sur ce piege le 2026-07-21).`,
+    `Synchronise depuis le projet (ex: cp ${projectSkillsDir}/${one}/SKILL.md ${globalSkillsDir}/${one}/SKILL.md) ou supprime la copie globale si elle n'est pas voulue.`,
+    `Rien n'est modifie automatiquement : une variante user-level peut etre deliberee.`,
+  ].join(' ');
+}
+
+module.exports = {
+  compareSkills,
+  formatReminder,
+  MAX_NAMES,
+};

package/install/templates/.claude/hooks/skill-freshness-check.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+'use strict';
+
+// SessionStart hook — stale-global-skill guard (I/O shell over
+// lib/skill-freshness.js).
+//
+// At each session start, compare the project's .claude/skills/<n>/SKILL.md with
+// the same-named ~/.claude/skills/<n>/SKILL.md. On a content divergence, inject
+// one bounded factual reminder (names + exact sync command). Silent when
+// everything is faithful, when there is no global copy, or when the project has
+// no skills. NEVER blocks a session: exit 0 on every path, including internal
+// errors. It never writes into ~/.claude — it reports, the human decides.
+
+const os = require('os');
+const path = require('path');
+const freshness = require('./lib/skill-freshness');
+
+function buildContext(projectDir, homeDir) {
+  const projectSkillsDir = path.join(projectDir, '.claude', 'skills');
+  const globalSkillsDir = path.join(homeDir, '.claude', 'skills');
+  const { diverged } = freshness.compareSkills({ projectSkillsDir, globalSkillsDir });
+  return freshness.formatReminder(diverged, {
+    projectSkillsDir: '.claude/skills',
+    globalSkillsDir: path.join(homeDir, '.claude', 'skills'),
+  });
+}
+
+if (require.main === module) {
+  try {
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    const ctx = buildContext(projectDir, os.homedir());
+    if (ctx) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: 'SessionStart',
+            additionalContext: ctx,
+          },
+        })
+      );
+    }
+  } catch {
+    // A guard must never take a session down with it.
+  }
+  process.exit(0);
+}
+
+module.exports = { buildContext };

package/install/templates/.claude/settings.json

@@ -15,6 +15,10 @@
           {
             "type": "command",
             "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/soul-memory-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
+          },
+          {
+            "type": "command",
+            "command": "p=\"$CLAUDE_PROJECT_DIR/.claude/hooks/skill-freshness-check.js\"; [ -f \"$p\" ] || exit 0; exec node \"$p\""
           }
         ]
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.53.0",
+  "version": "2.54.0",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Claude Code, Codex). Merise Agile + TDD + 71 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {