create-byan-agent 2.35.0 → 2.38.0

package/install/templates/.claude/hooks/lib/delivery-contract.js

@@ -0,0 +1,143 @@
+// Pure helpers for the BYAN delivery-default contract (F1).
+//
+// The user asked for something complete. This contract makes prod-grade +
+// maximal scope the DEFAULT the agent assumes every turn, instead of quietly
+// drifting toward an MVP / a short deliverable / a "split so the heavy part
+// does not block". It is the proactive twin of strict mode: strict locks a
+// scope on demand; this anchor sets the BASELINE posture before a scope is
+// even named.
+//
+// F1 ships LIVE (unlike the two blockers F2/F3): it is pure injected context,
+// it blocks nothing, so a false positive costs at most a few tokens — never a
+// trapped turn or a blocked commit. The only escape is an explicit opt-out word
+// the user types THIS message (mvp, quick, brouillon, ...), read from
+// _byan/_config/delivery-default.json so the wordlist is one source of truth.
+//
+// Every function here is pure (no clock, no fs beyond the one config read in
+// loadConfig) so the decision is unit-testable without a hook harness.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Fallback wordlist used only if the config file is missing/unreadable. Keeping
+// it here means the anchor still has a closed opt-out set on a broken install,
+// rather than treating every message as opt-out (fail-safe toward PROD).
+const DEFAULT_OPT_OUT_WORDS = [
+  'mvp',
+  'quick',
+  'brouillon',
+  'jette',
+  'prototype',
+  'vite fait',
+  'pas besoin que ce soit parfait',
+  'poc',
+  'draft',
+];
+
+function configPath(projectRoot) {
+  const root = projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  return path.join(root, '_byan', '_config', 'delivery-default.json');
+}
+
+function loadConfig(projectRoot) {
+  try {
+    const p = configPath(projectRoot);
+    if (fs.existsSync(p)) {
+      const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (cfg && typeof cfg === 'object') return cfg;
+    }
+  } catch {
+    // Fall through to defaults — a broken config must not silence the anchor.
+  }
+  return {};
+}
+
+function optOutWords(config) {
+  const words = config && Array.isArray(config.optOutWords) ? config.optOutWords : null;
+  return words && words.length ? words : DEFAULT_OPT_OUT_WORDS;
+}
+
+// The full delivery contract. PROD + MAXIMAL + the AI-2026 cost yardstick +
+// the explicit ban on proposing an MVP/short-deliverable/dont-block-the-heavy
+// split. Kept as one builder so the hook and the tests render identical text.
+function buildAnchor() {
+  return [
+    'CONTRAT DE LIVRAISON (defaut): grade=PROD. scope=MAXIMAL -- livre le maximum',
+    'coherent, INTERDIT de proposer un MVP/livrable-court/decoupage-pour-ne-pas-bloquer-le-lourd',
+    'sauf si l\'utilisateur a tape un mot opt-out CE message. Etalon de cout=AI-2026:',
+    'estime en temps-agent (x10), jamais en temps-humain-a-la-main. Tu es un fou',
+    'd\'optimisation: maximum a chaque demande, pas minimum.',
+  ].join(' ');
+}
+
+// Opt-out detection is BIASED TOWARD PROD. A false opt-out (silencing the prod
+// anchor when the user did not ask to) is the one failure that matters, so when
+// in doubt we stay PROD. A single opt-out word counts only when it reads as a
+// directive for THIS task -- the message is short enough to be a directive, OR
+// a "go-cheap" cue sits just before the word -- and it is dropped when negated
+// ("pas de mvp"). A word merely MENTIONED (a long meta message about MVPs, a
+// system notification, an "anti-mvp" discussion) leaves the anchor armed.
+// Curated multi-word phrases ("vite fait", "pas besoin que ce soit parfait")
+// are unambiguous and match as-is.
+const OPT_OUT_NEGATORS = new Set(['pas', 'sans', 'aucun', 'aucune', 'ni', 'no', 'not', 'non']);
+const OPT_OUT_CUES = new Set([
+  'juste', 'just', 'seulement', 'only', 'mode', 'reste', 'simplement',
+  'rapidement', 'vite', 'fais', 'make', 'leave', 'give', 'garde',
+]);
+const OPT_OUT_SHORT_WORDS = 30; // a message this short reads as a directive, not meta
+const OPT_OUT_WINDOW = 3; // tokens before the word inspected for a negator / cue
+
+function tokenizeWords(s) {
+  return s.toLowerCase().match(/[a-z0-9']+/g) || [];
+}
+
+function parseOptOut(userMsg, config) {
+  if (!userMsg || typeof userMsg !== 'string') return false;
+  const lower = userMsg.toLowerCase();
+  const words = optOutWords(config)
+    .map((w) => String(w).toLowerCase().trim())
+    .filter(Boolean);
+
+  // 1) Curated multi-word phrases: unambiguous opt-out intent, substring match.
+  if (words.some((w) => w.includes(' ') && lower.includes(w))) return true;
+
+  // 2) Single words: honoured only in a directive context, dropped when negated.
+  const singles = new Set(words.filter((w) => /^[a-z]+$/.test(w)));
+  if (singles.size === 0) return false;
+  const tokens = tokenizeWords(userMsg);
+  const directiveShort = tokens.length <= OPT_OUT_SHORT_WORDS;
+  for (let i = 0; i < tokens.length; i += 1) {
+    if (!singles.has(tokens[i])) continue;
+    const before = tokens.slice(Math.max(0, i - OPT_OUT_WINDOW), i);
+    if (before.some((t) => OPT_OUT_NEGATORS.has(t))) continue; // "pas de mvp" -> stays PROD
+    if (directiveShort || before.some((t) => OPT_OUT_CUES.has(t))) return true;
+  }
+  return false;
+}
+
+// The per-turn decision. With an opt-out word present this turn, emit a single
+// line authorizing descope; otherwise emit the full anchor. Pure: the caller
+// supplies the message and (optionally) the loaded config.
+function decideContext({ userMsg, config } = {}) {
+  const cfg = config || {};
+  const optOut = parseOptOut(userMsg, cfg);
+  if (optOut) {
+    return {
+      optOut: true,
+      text: 'CONTRAT DE LIVRAISON: OPT-OUT detecte ce message -- descope autorise (grade/scope libres pour cette demande).',
+    };
+  }
+  return { optOut: false, text: buildAnchor() };
+}
+
+module.exports = {
+  DEFAULT_OPT_OUT_WORDS,
+  configPath,
+  loadConfig,
+  optOutWords,
+  buildAnchor,
+  parseOptOut,
+  decideContext,
+};

package/install/templates/.claude/hooks/lib/punt-detect.js

@@ -0,0 +1,143 @@
+// Pure detector for the BYAN punt-guard (F3).
+//
+// A "punt" is the laziness pattern the user fights: the agent ends its turn by
+// telling the human to run a command and paste the output back, when the agent
+// could have run it itself this turn. The signal is a CO-OCCURRENCE in the
+// finished turn:
+//   1. an imperative addressed to the user ("lance", "execute", "colle la
+//      sortie", "run this", "paste", "donne-moi le ssh"), AND
+//   2. a runnable command (a backticked command, or a `node `/`npm `/`git `/
+//      `which `/`curl localhost` invocation), AND
+//   3. NO Bash tool-call for that command this turn (the agent did not actually
+//      run it — it handed it off).
+//
+// Carve-out (creds): `git push` and `npm publish` need credentials the server
+// running Claude Code does not have. Asking the user to run THOSE is legitimate,
+// not a punt — documented in MEMORY (server cannot push). So a command whose
+// runnable token is a push/publish is never flagged.
+//
+// This module is pure decide() — no fs, no stdin — so it is exhaustively
+// unit-testable. The hook wires it to the transcript and the arm flag.
+
+'use strict';
+
+// Imperatives addressed to the user that, paired with a runnable command, mean
+// "you run it". FR + EN. Matched case-insensitively as loose phrases.
+const PUNT_IMPERATIVES = [
+  'lance',
+  'execute',
+  'exécute',
+  'colle la sortie',
+  'colle le resultat',
+  'colle le résultat',
+  'run this',
+  'run it',
+  'paste',
+  'donne-moi le ssh',
+  'donne moi le ssh',
+  'peux-tu lancer',
+  'peux tu lancer',
+  'lance la commande',
+];
+
+// Commands that need creds the server lacks. Asking the user to run these is
+// legitimate (not a punt). Order matters only for reporting the matched token.
+const CREDS_CARVEOUT = ['git push', 'npm publish'];
+
+// Loose runnable-command detectors. A backticked span, or a bare invocation of
+// a common runner at a word boundary. `curl localhost` is included because the
+// dev API runs on localhost and the agent can hit it itself.
+const RUNNABLE_PATTERNS = [
+  /`([^`]+)`/g, // any backticked span
+  /\bnode\s+\S+/gi,
+  /\bnpm\s+\S+/gi,
+  /\bgit\s+\S+/gi,
+  /\bwhich\s+\S+/gi,
+  /\bcurl\s+localhost\S*/gi,
+];
+
+function hasImperativeToUser(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return PUNT_IMPERATIVES.some((p) => lower.includes(p));
+}
+
+// Returns the first runnable command found in the text, or null. Backticked
+// spans win (they are the explicit "here is the command" form); else the first
+// bare invocation. The returned string is the matched command text.
+function findRunnableCommand(text) {
+  if (!text) return null;
+  for (const re of RUNNABLE_PATTERNS) {
+    re.lastIndex = 0;
+    const m = re.exec(text);
+    if (m) {
+      // Backtick pattern captures group 1 (the inner command); the bare-runner
+      // patterns have no capture group, so use the full match.
+      return (m[1] !== undefined ? m[1] : m[0]).trim();
+    }
+  }
+  return null;
+}
+
+// True when the command is a creds-gated push/publish (legitimate to delegate).
+function isCredsCarveOut(cmd) {
+  if (!cmd) return false;
+  const lower = cmd.toLowerCase();
+  return CREDS_CARVEOUT.some((c) => lower.includes(c));
+}
+
+// True when a Bash tool-call this turn actually ran (something matching) the
+// command. We match on the meaningful head token of the command (e.g. "npm
+// test" -> we require the Bash command to include "npm test"), so a Bash call
+// that ran a DIFFERENT command does not falsely clear the punt. toolCalls is an
+// array of { name, command } where command is the Bash tool's command string.
+function bashRanCommand(toolCalls, cmd) {
+  if (!Array.isArray(toolCalls) || !cmd) return false;
+  // Compare on a normalized, whitespace-collapsed head so minor formatting
+  // (extra spaces, trailing flags in the prose) does not break the match.
+  const needle = cmd.toLowerCase().replace(/\s+/g, ' ').trim();
+  const headTokens = needle.split(' ').slice(0, 2).join(' '); // e.g. "npm test"
+  return toolCalls.some((tc) => {
+    if (!tc || typeof tc.name !== 'string') return false;
+    if (!/bash/i.test(tc.name)) return false;
+    const ran = String(tc.command || '').toLowerCase().replace(/\s+/g, ' ').trim();
+    if (!ran) return false;
+    return ran.includes(needle) || (headTokens.length > 0 && ran.includes(headTokens));
+  });
+}
+
+// Pure decision. Returns { punt, reason, cmd }.
+//   punt  : true IFF imperative-to-user + runnable command + NOT a creds
+//           carve-out + NO Bash tool-call ran that command this turn.
+//   reason: a short human-readable explanation (or why it is not a punt).
+//   cmd   : the runnable command detected (or null).
+function decide({ lastAssistantText, toolCallsThisTurn } = {}) {
+  const text = lastAssistantText || '';
+  const imperative = hasImperativeToUser(text);
+  const cmd = findRunnableCommand(text);
+
+  if (!imperative || !cmd) {
+    return { punt: false, reason: 'no imperative-to-user + runnable command co-occurrence', cmd: cmd || null };
+  }
+  if (isCredsCarveOut(cmd)) {
+    return { punt: false, reason: `creds carve-out: "${cmd}" needs credentials the server lacks`, cmd };
+  }
+  if (bashRanCommand(toolCallsThisTurn, cmd)) {
+    return { punt: false, reason: `agent ran the command via Bash this turn: "${cmd}"`, cmd };
+  }
+  return {
+    punt: true,
+    reason: `punt detected: asked the user to run "${cmd}" without running it via Bash this turn`,
+    cmd,
+  };
+}
+
+module.exports = {
+  PUNT_IMPERATIVES,
+  CREDS_CARVEOUT,
+  hasImperativeToUser,
+  findRunnableCommand,
+  isCredsCarveOut,
+  bashRanCommand,
+  decide,
+};

package/install/templates/.claude/hooks/punt-guard.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+/**
+ * Stop hook — BYAN punt-guard (F3).
+ *
+ * Goal : catch the laziness pattern where the agent ends its turn by telling the
+ * user to run a command and paste the output back, when the agent could have run
+ * it itself (a Bash tool-call) this turn. The pure detection lives in
+ * lib/punt-detect.js; this hook wires it to the real Stop payload and the arm
+ * flag.
+ *
+ * Ships DISARMED (puntGuard.armed=false in _byan/_config/delivery-default.json),
+ * same posture as the autobench Stop guard. Arming a Stop blocker without first
+ * measuring false positives breaks the flow. So by default the hook only
+ * OBSERVES: it appends one line to _byan-output/punt-ledger.jsonl
+ * (observed-disarmed / observed-disarmed-punt) and exits 0. Only when armed does
+ * it block (exit 2) on a detected punt.
+ *
+ * Carve-out (in punt-detect): git push / npm publish are never flagged — the
+ * server has no creds, so delegating those to the user is legitimate.
+ *
+ * Non-blocking on any IO/parse error : the hook never traps a turn it cannot read.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { decide } = require('./lib/punt-detect');
+const { loadConfig } = require('./lib/delivery-contract');
+// transcript-read is the canonical Stop-payload reader (text + raw content); it
+// does NOT carry stdin helpers, so readStdin/parseJson come from strict-runtime
+// like the other Stop/prompt hooks.
+const { extractLastAssistantText, extractLastAssistantContent } = require('./lib/transcript-read');
+const { readStdin, parseJson } = require('./lib/strict-runtime');
+
+function projectRoot() {
+  return process.env.CLAUDE_PROJECT_DIR || process.cwd();
+}
+
+function isArmed(config) {
+  const pg = config && config.puntGuard;
+  return !!(pg && pg.armed === true);
+}
+
+// Pull the Bash tool-calls out of the finished assistant turn's RAW content.
+// transcript-read gives the block array; a Bash tool_use is
+// { type:'tool_use', name:'Bash', input:{ command } }. Returns [{ name, command }].
+function bashToolCalls(content) {
+  if (!Array.isArray(content)) return [];
+  const out = [];
+  for (const b of content) {
+    if (b && b.type === 'tool_use' && typeof b.name === 'string') {
+      const command = b.input && typeof b.input.command === 'string' ? b.input.command : '';
+      out.push({ name: b.name, command });
+    }
+  }
+  return out;
+}
+
+function ledgerPath() {
+  return path.join(projectRoot(), '_byan-output', 'punt-ledger.jsonl');
+}
+
+function appendLedger(entry) {
+  try {
+    const p = ledgerPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.appendFileSync(p, JSON.stringify(entry) + '\n');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (require.main === module) {
+  (async () => {
+    // Wrap everything : the hook must NEVER trap a turn it cannot read.
+    try {
+      const config = loadConfig(projectRoot());
+      const payload = parseJson(await readStdin());
+      const lastAssistantText = extractLastAssistantText(payload);
+      const toolCallsThisTurn = bashToolCalls(extractLastAssistantContent(payload));
+
+      const result = decide({ lastAssistantText, toolCallsThisTurn });
+      const armed = isArmed(config);
+
+      const event = armed
+        ? result.punt
+          ? 'fired-block'
+          : 'no-punt'
+        : result.punt
+          ? 'observed-disarmed-punt'
+          : 'observed-disarmed';
+
+      appendLedger({
+        event,
+        punt: result.punt,
+        cmd: result.cmd || undefined,
+        reason: result.reason,
+        armed,
+        ts: process.env.BYAN_HOOK_TS || undefined,
+        session: process.env.CLAUDE_SESSION_ID || undefined,
+      });
+
+      if (armed && result.punt) {
+        const reason =
+          `Punt-guard: you asked the user to run "${result.cmd}" and paste the output, ` +
+          `but you did not run it via Bash this turn. Run it yourself, then report the result. ` +
+          `(git push / npm publish are exempt — the server has no creds for those.)`;
+        process.stdout.write(
+          JSON.stringify({ decision: 'block', reason, systemMessage: reason })
+        );
+        process.exit(2);
+      }
+
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    } catch {
+      // Last-resort net : on any unexpected failure, let the turn end.
+      process.stdout.write(JSON.stringify({ continue: true }));
+      process.exit(0);
+    }
+  })();
+}
+
+module.exports = { bashToolCalls, isArmed, ledgerPath, appendLedger };

package/install/templates/.claude/hooks/strict-stop-guard.js

@@ -23,15 +23,38 @@ const { extractLastAssistantText } = require('./lib/transcript-read');
 
 const DEFAULT_MARKERS = ['done', 'finished', 'complete', 'delivered', 'ready'];
 
+// Strip the contexts where a completion marker is a MENTION, not a CLAIM:
+// fenced + inline code, HTML comments (the BYAN-BENCH:done marker lives there),
+// and snake_case / namespaced identifiers (byan_strict_complete, BENCH:done). A
+// marker that survives this strip is prose -- the only place a real "it is done"
+// claim lives. Exported so the regression cases are unit-testable.
+function denoiseForClaim(text) {
+  return String(text)
+    .replace(/```[\s\S]*?```/g, ' ') // fenced code blocks
+    .replace(/`[^`]*`/g, ' ') // inline code spans
+    .replace(/<!--[\s\S]*?-->/g, ' ') // HTML comments (e.g. <!-- BYAN-BENCH:done -->)
+    .replace(/[A-Za-z0-9]+(?:[_:][A-Za-z0-9]+)+/g, ' '); // snake_case / ns identifiers
+}
+
+// A completion marker counts only as a STANDALONE claim, bounded by non-letters
+// (Unicode-aware via the u flag, so "indefini" does not embed "fini" and
+// "determine" does not embed "termine"), with a permissive trailing inflection
+// (livre -> livree / livres). Bias: a false negative is caught by the pre-commit
+// gate (the hard net), while a false positive traps a legitimate turn -- so a
+// marker that is only mentioned is NOT read as a claim.
 function claimsCompletion(text, markers) {
   if (!text) return false;
-  const lower = text.toLowerCase();
+  const clean = denoiseForClaim(text).toLowerCase();
   return (markers || DEFAULT_MARKERS).some((m) => {
-    const marker = String(m).toLowerCase();
-    if (/^[a-z]+$/.test(marker)) {
-      return new RegExp(`\\b${marker}\\b`).test(lower);
+    const marker = String(m).toLowerCase().trim();
+    if (!marker) return false;
+    const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    try {
+      return new RegExp(`(?<![\\p{L}])${escaped}(?:s|e|es|ée|ées|és)?(?![\\p{L}])`, 'iu').test(clean);
+    } catch {
+      // Older runtimes without lookbehind/\p{L} -> fall back to a plain include.
+      return clean.includes(marker);
     }
-    return lower.includes(marker);
   });
 }
 
@@ -85,4 +108,4 @@ if (require.main === module) {
   })();
 }
 
-module.exports = { decideStop, claimsCompletion, extractLastAssistantText };
+module.exports = { decideStop, claimsCompletion, denoiseForClaim, extractLastAssistantText };

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

@@ -27,6 +27,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-voice-anchor.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/inject-delivery-default.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/soul-memory-triggers.js"
@@ -70,6 +74,10 @@
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/autobench-stop-guard.js"
           },
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/punt-guard.js"
+          },
           {
             "type": "command",
             "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/drain-advisory.js"

package/install/templates/_byan/_config/delivery-default.json

@@ -0,0 +1,22 @@
+{
+  "version": 1,
+  "name": "BYAN Delivery Default",
+  "description": "Makes prod-grade + maximal scope the mechanical default. F1 (the delivery-contract anchor) ships LIVE: it is pure injected context, no risk. F2 (completeness reject) and F3 (punt-guard) ship DISARMED behind armed flags: arming a turn/commit blocker without first measuring false positives would break the flow and could lock an in-progress strict session.",
+  "optOutWords": [
+    "mvp",
+    "quick",
+    "brouillon",
+    "jette",
+    "prototype",
+    "vite fait",
+    "pas besoin que ce soit parfait",
+    "poc",
+    "draft"
+  ],
+  "completenessGate": {
+    "armed": false
+  },
+  "puntGuard": {
+    "armed": false
+  }
+}

package/install/templates/_byan/mcp/byan-mcp-server/channel-entry.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * channel-entry.js — Entrypoint stdio du channel MCP byan pour Claude Code.
+ *
+ * POURQUOI un fichier séparé de server.js : le channel est un serveur MCP
+ * distinct du serveur principal byan-mcp. Claude Code le spawne comme un
+ * subprocess indépendant via --dangerously-load-development-channels.
+ * server.js ne doit pas acquérir le transport channel comme effet de bord.
+ *
+ * Commande de lancement (research preview) :
+ *   claude --dangerously-load-development-channels server:byan-channel
+ *
+ * Enregistrement dans .mcp.json (section mcpServers) — exactement ce que pose
+ * l'installeur : chemin RELATIF au projectRoot (portable, jamais absolu) et env
+ * VIDE (la config est resolue au boot via resolveConfig ci-dessous ; aucun secret
+ * n'est ecrit dans .mcp.json qui est tracke par git) :
+ *   "byan-channel": {
+ *     "command": "node",
+ *     "args": ["_byan/mcp/byan-mcp-server/channel-entry.js"],
+ *     "env": {}
+ *   }
+ *
+ * Voie plugin (Phase 2, non implémentée ici) :
+ *   Wrapper le channel-entry.js dans un plugin Claude Code et l'enregistrer
+ *   dans la marketplace pour qu'il soit accessible via
+ *   --channels plugin:byan-channel@byan-marketplace.
+ *   Nécessite que le channel soit sur l'allowlist Anthropic ou sur la liste
+ *   allowedChannelPlugins de l'organisation (Enterprise).
+ */
+
+import { resolveConfig } from './lib/resolve-config.js';
+import { runChannelStdio } from './lib/channel-server.js';
+
+// Config : même resolver que server.js (env -> ~/.byan/credentials.json -> défauts).
+const config = resolveConfig();
+const apiUrl   = config.BYAN_API_URL   || process.env.BYAN_API_URL;
+const apiToken = config.BYAN_API_TOKEN || process.env.BYAN_API_TOKEN;
+
+if (!apiUrl) {
+  process.stderr.write('[byan-channel] BYAN_API_URL manquant — le poll sera désactivé\n');
+}
+if (!apiToken) {
+  process.stderr.write('[byan-channel] BYAN_API_TOKEN manquant — le poll et les replies seront désactivés\n');
+}
+
+await runChannelStdio({ apiUrl, apiToken });