@xmarts/genius-setup 1.7.1 → 1.8.0

package/CLAUDE_PROTOCOL.md

@@ -9,6 +9,10 @@ El Brain de Genius está conectado vía el MCP **`beesmart_genius`** y dos hooks
   learnings, playbooks y patrones relevantes — no tienes que pedirlos.
 - **Captura automática** (SessionEnd/PreCompact/Stop): tus hallazgos y tu sesión se capturan solos al
   final; no tienes que documentar manualmente.
+- **Enforcement de plan/comité** (Stop): si una sesión generó un **plan** o convocó un **comité** pero
+  no se capturó **ningún** learning al Brain, el guard bloquea el cierre **una sola vez** y te recuerda
+  destilarlo con `capture_learning`. Falla-abierto (nunca te atrapa) y se puede ajustar por máquina con
+  `XMA_PLAN_GUARD_MODE=block|warn|off`.
 - **Auto-actualización**: el paquete se refresca solo en segundo plano (1×/día). Cuando agregamos tools,
   skills o features, las recibes en tus turnos **sin hacer nada**.
 
@@ -21,6 +25,13 @@ El Brain de Genius está conectado vía el MCP **`beesmart_genius`** y dos hooks
 5. **NUNCA te conectes directo al Odoo del cliente** — todo fluye por el MCP `beesmart_genius`.
 6. Tu tiempo se sugiere solo a partir de tu actividad; confírmalo cuando puedas en **My Week**
    (`/mcp/webapp/my-week`). Solo el tiempo que confirmas cuenta como horas reales.
+7. **PLAN o COMITÉ ⇒ captura MANDATORIA al Brain.** Siempre que generes un **plan** (modo plan /
+   estrategia aprobada) o convoques un **comité** (multi-agente / Workflow / panel), es OBLIGATORIO
+   destilar sus perspectivas, análisis, soluciones, decision-records y estrategia en learnings vía
+   `capture_learning` (central/universal — **sin** `target_client`) **ANTES de cerrar la tarea**. El
+   análisis de un plan/comité ES conocimiento durable: la tarea **no está terminada** hasta que el Brain
+   quedó alimentado (move-list + hallazgos + alternativas rechazadas + gotchas + pasos human-gated, cada
+   uno con su `forward_directive`). El guard de Stop lo hace cumplir por máquina.
 
 ## Tools (servidas dinámicamente por `beesmart_genius`)
 

package/bin/genius-setup.js

@@ -148,6 +148,7 @@ function runSetup(token) {
   }
   const hookDst = copyHook('genius_capture.py');
   const injectDst = copyHook('genius_inject.py');
+  const guardDst = copyHook('plan_committee_guard.py');
 
   // 2) ~/.claude.json mcpServers (merge, no clobber)
   const claudeJsonPath = path.join(HOME, '.claude.json');
@@ -179,6 +180,12 @@ function runSetup(token) {
   ['SessionEnd', 'PreCompact', 'Stop'].forEach((e) => addHook(e, hookDst));
   // Per-turn knowledge injection + session priming (consultant_access guarantee).
   ['UserPromptSubmit', 'SessionStart'].forEach((e) => addHook(e, injectDst));
+  // Plan/committee -> Brain capture ENFORCEMENT (CLAUDE.md §6). On Stop it blocks the
+  // turn ONCE if a plan or committee ran this session without any capture_learning.
+  // Fails open, blocks at most once per session, and is mode-overridable per machine
+  // (XMA_PLAN_GUARD_MODE=block|warn|off). Unlike the fire-and-forget hooks above, this
+  // one can return {"decision":"block"} — by design — but never traps a session.
+  addHook('Stop', guardDst);
   writeJson(settingsPath, settings);
 
   // 4) ~/.claude/CLAUDE.md — install/refresh the Genius Protocol between auto-managed
@@ -209,6 +216,7 @@ function runSetup(token) {
   log('  - MCP server     : beesmart_genius -> ' + BASE + '/mcp/consultant');
   log('  - Capture hook   : ' + hookDst + '  (SessionEnd / PreCompact / Stop)');
   log('  - Inject hook    : ' + injectDst + '  (UserPromptSubmit / SessionStart)');
+  log('  - Plan/committee : ' + guardDst + '  (Stop — enforces plan/comité → Brain; XMA_PLAN_GUARD_MODE=block|warn|off)');
   log('  - Config         : ' + path.join(GENIUS_DIR, 'config.json'));
   log('  - Protocol       : ' + path.join(CLAUDE_DIR, 'CLAUDE.md') + '  (auto-managed)');
   if (CLIENT) log('  - Default client : ' + CLIENT);

package/hooks/genius_inject.py

@@ -63,7 +63,7 @@ def _inject(cfg, prompt):
     base = (cfg.get("base_url") or "https://beesmart.digital").rstrip("/")
     token = cfg.get("token")
     if not token or not prompt.strip():
-        return ""
+        return "", None, None
     body = json.dumps({"jsonrpc": "2.0", "method": "call", "id": 1,
                        "params": {"prompt": prompt[:4000], "limit": 4}}).encode()
     req = urllib.request.Request(base + "/xma/genius/v1/inject", data=body)
@@ -75,13 +75,34 @@ def _inject(cfg, prompt):
         resp = urllib.request.urlopen(req, timeout=TIMEOUT)
         data = json.loads(resp.read())
         result = data.get("result", data) or {}
-        return (result.get("context", "") or ""), result.get("hook_force_epoch")
+        return ((result.get("context", "") or ""),
+                result.get("hook_force_epoch"),
+                result.get("hook_pin_version"))
     except Exception:
-        return "", None
+        return "", None, None
 
 
-def _maybe_self_update(cfg, force_epoch=None):
-    """Keep the consultant on the LATEST Genius package with ZERO action: at most
+# M6 (Phase-0 integrity gate): NEVER resolve `@latest`. An unsigned `npx @latest`
+# self-update is a standing fleet-wide RCE channel. We install an EXACT pinned
+# version dictated by the server (xma_genius.hook_pin_version, returned in the
+# inject response) and otherwise fall back to this bundled known-good pin — the
+# client never resolves the mutable `@latest` tag.
+PINNED_FALLBACK = "1.7.2"
+
+
+def _pkg_spec(pin_version):
+    """Resolve the exact package spec to install. Accepts only a plain semver pin
+    from the server; anything else falls back to the bundled PINNED_FALLBACK.
+    Never returns an `@latest` spec."""
+    import re
+    v = (pin_version or "").strip()
+    if v and re.match(r"^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.]+)?$", v):
+        return "@xmarts/genius-setup@%s" % v
+    return "@xmarts/genius-setup@%s" % PINNED_FALLBACK
+
+
+def _maybe_self_update(cfg, force_epoch=None, pin_version=None):
+    """Keep the consultant on the SERVER-PINNED Genius package with ZERO action: at most
     once/day, silently re-run the installer in the background. New hooks, MCP
     tools, settings and the CLAUDE.md protocol then flow automatically — the
     consultant never re-onboards. Detached + fully guarded; never blocks a turn.
@@ -124,15 +145,16 @@ def _maybe_self_update(cfg, force_epoch=None):
         env = dict(os.environ)
         env["GENIUS_TOKEN"] = token
         base = cfg.get("base_url")
+        spec = _pkg_spec(pin_version)  # exact pinned version — never @latest
         devnull = open(os.devnull, "w")
         if os.name == "nt":
-            cmd = "npx -y @xmarts/genius-setup@latest"
+            cmd = "npx -y %s" % spec
             if base:
                 cmd += ' --base-url "%s"' % base
             subprocess.Popen(cmd, shell=True, env=env, stdout=devnull, stderr=devnull,
                              stdin=subprocess.DEVNULL, creationflags=0x00000008)  # DETACHED_PROCESS
         else:
-            args = ["npx", "-y", "@xmarts/genius-setup@latest"]
+            args = ["npx", "-y", spec]
             if base:
                 args += ["--base-url", base]
             subprocess.Popen(args, env=env, stdout=devnull, stderr=devnull,
@@ -152,10 +174,11 @@ def main():
         _maybe_self_update(cfg)   # TTL-only on priming
         _emit("SessionStart", SESSION_PRIMER)
     else:
-        context, force_epoch = _inject(cfg, event.get("prompt") or "")
+        context, force_epoch, pin_version = _inject(cfg, event.get("prompt") or "")
         # The inject call already round-tripped the server, so honour any
-        # admin-pushed force-update epoch here (bypasses the daily TTL).
-        _maybe_self_update(cfg, force_epoch)
+        # admin-pushed force-update epoch here (bypasses the daily TTL) and install
+        # the exact server-pinned version (never @latest).
+        _maybe_self_update(cfg, force_epoch, pin_version)
         _emit("UserPromptSubmit", context)
 
 

package/hooks/plan_committee_guard.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+plan_committee_guard.py — machine enforcement of the canonical Genius rule:
+
+    "Plan o comité ⇒ captura MANDATORIA al Brain"  (CLAUDE.md §6 / CLAUDE_PROTOCOL.md)
+
+Fires on the Claude Code **Stop** event (end of a main-agent turn). It scans the
+session transcript: if this session generated a PLAN (plan mode / ExitPlanMode, a
+`~/.claude/plans/` file, or the writing-plans skill) or convened a COMMITTEE (a
+`Workflow` run or a subagent fan-out) but captured ZERO learnings to the Genius Brain
+(`mcp__beesmart_genius__capture_learning`), it BLOCKS the Stop once with a directive
+telling Claude to distill the plan/committee into the Brain before finishing.
+
+This is the enforcement layer for THIS session and for EVERY consultant session —
+it ships with @xmarts/genius-setup (npx rail → ~/.genius/hooks/) and the
+`xmarts-genius` plugin (plugin/hooks/hooks.json → ${CLAUDE_PLUGIN_ROOT}/hooks/).
+
+DESIGN GUARANTEES (the §15 "never break a session" discipline):
+  * FAILS OPEN — any parse/IO/unknown error → exit 0 (allow the Stop). A hook must
+    never trap or crash a consultant's session.
+  * BLOCKS AT MOST ONCE per session (state file under ~/.genius/state/). After the
+    single nudge it degrades to a non-blocking log line, so if the Brain is
+    unreachable or Claude can't capture, the user is NEVER trapped in a loop.
+  * Honors `stop_hook_active` to avoid stop-loops.
+  * Only nudges once REAL post-plan work exists (a mutation after the plan signal, or
+    >= MIN_TURNS_AFTER_SIGNAL assistant turns), so it doesn't interrupt mid-planning.
+  * The block is delivered as STDOUT JSON {"decision":"block","reason":...} + exit 0,
+    so it survives the installer's `... || true` command wrapper (which only forces the
+    exit code, not stdout).
+  * Mode override per machine via env:
+        XMA_PLAN_GUARD_MODE = block (default) | warn (log only, never blocks) | off
+
+A single deliberate capture_learning call clears the debt — the guard never audits
+"enough" captures, it only insists the plan/committee was fed to the Brain at all.
+"""
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+# --- tunables (env-overridable) ---------------------------------------------
+MODE = (os.environ.get("XMA_PLAN_GUARD_MODE", "block") or "block").strip().lower()
+try:
+    MIN_TURNS_AFTER_SIGNAL = int(os.environ.get("XMA_PLAN_GUARD_MIN_TURNS", "3"))
+except Exception:
+    MIN_TURNS_AFTER_SIGNAL = 3
+MAX_BLOCKS_PER_SESSION = 1
+SUBAGENT_THRESHOLD = 4  # >= this many Task/Agent subagent calls ≈ a committee fan-out
+
+# --- signal vocabulary ------------------------------------------------------
+PLAN_TOOLS = {"ExitPlanMode", "EnterPlanMode"}
+PLAN_SKILLS = {"writing-plans", "executing-plans"}
+PLAN_FILE_HINT = "/.claude/plans/"
+COMMITTEE_TOOLS = {"Workflow"}
+COMMITTEE_SKILLS = {"dispatching-parallel-agents", "subagent-driven-development"}
+SUBAGENT_TOOLS = {"Task", "Agent"}
+CAPTURE_SUFFIX = "__capture_learning"
+MUTATION_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit", "Bash"}
+MUTATION_SUBSTR = ("create_record", "update_record", "delete_record",
+                   "manage_module", "manage_webapp", "execute_orm", "execute_method")
+
+STATE_DIR = Path(os.path.expanduser("~/.genius/state/plan_committee_guard"))
+LOG_FILE = STATE_DIR / "guard.log"
+
+
+def _log(msg):
+    try:
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        with open(LOG_FILE, "a") as f:
+            f.write("%s %s\n" % (time.strftime("%Y-%m-%dT%H:%M:%S"), msg))
+    except Exception:
+        pass
+
+
+def _allow():
+    """Allow the Stop (success, no block)."""
+    sys.exit(0)
+
+
+def _iter_tool_uses(obj):
+    """Yield (name, input_dict) for every tool_use block in a transcript line object."""
+    if not isinstance(obj, dict):
+        return
+    msg = obj.get("message")
+    content = msg.get("content") if isinstance(msg, dict) else None
+    if isinstance(content, list):
+        for item in content:
+            if isinstance(item, dict) and item.get("type") == "tool_use":
+                yield (item.get("name") or ""), (item.get("input") or {})
+
+
+def _is_assistant(obj):
+    if not isinstance(obj, dict):
+        return False
+    if obj.get("type") == "assistant":
+        return True
+    msg = obj.get("message")
+    return isinstance(msg, dict) and msg.get("role") == "assistant"
+
+
+def _is_mutation(name):
+    if name in MUTATION_TOOLS:
+        return True
+    return any(s in name for s in MUTATION_SUBSTR)
+
+
+def scan(transcript_path):
+    """One pass over the JSONL transcript. Returns detections (cheap pre-filter then parse)."""
+    plan = committee = False
+    capture_count = 0
+    subagent_count = 0
+    committee_from_subagent = False
+    signal_idx = None          # index of first plan/committee signal line
+    mutation_after = False
+    assistant_turns_after = 0
+
+    with open(transcript_path, "r", errors="ignore") as f:
+        for idx, line in enumerate(f):
+            # cheap pre-filter: skip lines that cannot carry a tool_use or an assistant turn
+            if ('"tool_use"' not in line) and ('"assistant"' not in line):
+                continue
+            try:
+                obj = json.loads(line)
+            except Exception:
+                continue
+
+            line_has_signal = False
+            for name, inp in _iter_tool_uses(obj):
+                # --- plan signals ---
+                if name in PLAN_TOOLS:
+                    plan = True
+                    line_has_signal = True
+                if name == "Skill":
+                    sk = (inp.get("skill") or inp.get("command") or "") if isinstance(inp, dict) else ""
+                    if sk in PLAN_SKILLS:
+                        plan = True
+                        line_has_signal = True
+                    if sk in COMMITTEE_SKILLS:
+                        committee = True
+                        line_has_signal = True
+                if name in ("Write", "Edit", "MultiEdit", "NotebookEdit"):
+                    fp = ""
+                    if isinstance(inp, dict):
+                        fp = inp.get("file_path") or inp.get("notebook_path") or ""
+                    if PLAN_FILE_HINT in fp:
+                        plan = True
+                        line_has_signal = True
+                # --- committee signals ---
+                if name in COMMITTEE_TOOLS:
+                    committee = True
+                    line_has_signal = True
+                if name in SUBAGENT_TOOLS:
+                    subagent_count += 1
+                # --- capture (clears the debt) ---
+                if name.endswith(CAPTURE_SUFFIX):
+                    capture_count += 1
+                # --- mutation-after bookkeeping ---
+                if signal_idx is not None and idx > signal_idx and _is_mutation(name):
+                    mutation_after = True
+
+            # subagent fan-out crossing the threshold is itself a committee signal (once)
+            if (not committee_from_subagent) and subagent_count >= SUBAGENT_THRESHOLD:
+                committee = True
+                committee_from_subagent = True
+                line_has_signal = True
+
+            if line_has_signal and signal_idx is None:
+                signal_idx = idx
+
+            if signal_idx is not None and idx > signal_idx and _is_assistant(obj):
+                assistant_turns_after += 1
+
+    return {
+        "plan": plan,
+        "committee": committee,
+        "capture_count": capture_count,
+        "subagent_count": subagent_count,
+        "signal_idx": signal_idx,
+        "mutation_after": mutation_after,
+        "assistant_turns_after": assistant_turns_after,
+    }
+
+
+def main():
+    raw = sys.stdin.read()
+    try:
+        data = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        _allow()
+
+    if MODE == "off":
+        _allow()
+
+    event = data.get("hook_event_name") or ""
+    if event and event != "Stop":
+        # Defensive: this guard only enforces on Stop. Any other wiring → allow.
+        _allow()
+
+    transcript = os.path.expanduser(data.get("transcript_path") or "")
+    if not transcript or not os.path.exists(transcript):
+        _allow()
+
+    try:
+        det = scan(transcript)
+    except Exception as e:
+        _log("scan-error %s" % e)
+        _allow()
+
+    debt = (det["plan"] or det["committee"]) and det["capture_count"] == 0
+    if not debt:
+        _allow()
+
+    kind = "plan" if det["plan"] else "comité"
+    session_id = str(data.get("session_id") or "unknown")
+
+    # never loop on a stop-hook continuation
+    if data.get("stop_hook_active"):
+        _log("session=%s debt=%s stop_hook_active -> allow" % (session_id, kind))
+        _allow()
+
+    # substantial-work gate: don't nudge mid-planning (wait for real post-plan work)
+    substantial = det["mutation_after"] or det["assistant_turns_after"] >= MIN_TURNS_AFTER_SIGNAL
+    if not substantial:
+        _log("session=%s debt=%s not-yet-substantial -> allow" % (session_id, kind))
+        _allow()
+
+    # block-once-per-session state
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    state_file = STATE_DIR / ("%s.json" % session_id.replace("/", "_"))
+    state = {}
+    if state_file.exists():
+        try:
+            state = json.loads(state_file.read_text())
+        except Exception:
+            state = {}
+    blocks = int(state.get("blocks", 0))
+
+    if MODE == "warn" or blocks >= MAX_BLOCKS_PER_SESSION:
+        _log("session=%s debt=%s mode=%s blocks=%d -> advise-only (allow)"
+             % (session_id, kind, MODE, blocks))
+        _allow()
+
+    state["blocks"] = blocks + 1
+    state["last"] = time.strftime("%Y-%m-%dT%H:%M:%S")
+    state["kind"] = kind
+    try:
+        state_file.write_text(json.dumps(state))
+    except Exception:
+        pass
+    _log("session=%s debt=%s BLOCK#%d" % (session_id, kind, blocks + 1))
+
+    reason = (
+        u"⛔ Captura-debt al Genius Brain (regla canónica CLAUDE.md §6 / "
+        u"Protocolo de Consultor).\n"
+        u"Esta sesión generó un %s pero NO se capturó ningún learning al Brain "
+        u"(0 llamadas a capture_learning).\n\n"
+        u"ANTES de cerrar: destilá el %s al Brain vía mcp__beesmart_genius__capture_learning "
+        u"(central/universal — SIN target_client). Capturá, como mínimo: la move-list / "
+        u"decisiones, los hallazgos clave + alternativas rechazadas, los gotchas / breaking-changes, "
+        u"y los pasos human-gated — cada uno con su forward_directive (category best_practice o "
+        u"pattern).\n\n"
+        u"Si ya capturaste fuera de esta sesión, o el Brain está inalcanzable: anotalo en una "
+        u"línea y entonces sí podés cerrar (este recordatorio es de UNA sola vez por sesión)."
+    ) % (kind, kind)
+
+    sys.stdout.write(json.dumps({"decision": "block", "reason": reason}))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except SystemExit:
+        raise
+    except Exception as e:  # absolute backstop — never break a session
+        _log("fatal %s" % e)
+        sys.exit(0)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xmarts/genius-setup",
-  "version": "1.7.1",
-  "description": "One-command, self-updating onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session/time capture + CLAUDE.md protocol). Secret-free onboarding via single-use setup-token exchange (no Bearer in the GET-able bootstrap). Installs once; self-updates daily so new tools/skills/features arrive with zero action.",
+  "version": "1.8.0",
+  "description": "One-command, self-updating onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session/time capture + plan/committee→Brain enforcement + CLAUDE.md protocol). Secret-free onboarding via single-use setup-token exchange (no Bearer in the GET-able bootstrap). Installs once; self-updates daily so new tools/skills/features arrive with zero action.",
   "bin": {
     "genius-setup": "bin/genius-setup.js"
   },
@@ -9,6 +9,7 @@
     "bin/genius-setup.js",
     "hooks/genius_inject.py",
     "hooks/genius_capture.py",
+    "hooks/plan_committee_guard.py",
     "CLAUDE_PROTOCOL.md",
     "README.md"
   ],