nexo-brain 5.3.20 → 5.3.21

package/src/skills/run-nexo-audit-phase/guide 2.md

@@ -0,0 +1,43 @@
+# Run NEXO Audit Phase
+
+Usa esta skill cuando haya que ejecutar una fase de auditoria de NEXO y el cuello de botella sea decidir el alcance de `evolution_apply` y arrancar una tanda de items con disciplina empirica.
+
+## Pasos
+1. Abre `goal + workflow + task` y fija el terreno real antes de interpretar el informe:
+   - repo/runtime activo
+   - DB real
+   - mecanismo de update
+   - tests y estado git
+2. Fija la regla de autonomia antes de empezar:
+   - Francisco no quiere checkpoints uno-a-uno para trabajo mecanico
+   - NEXO hace branches, PRs, merge y reporta despues con evidencia
+   - solo un blast radius arquitectonico enorme merece checkpoint
+3. Trata `evolution_apply` como una decision tecnica de implementacion, no como permiso humano:
+   - el camino de apply ya existe via `evolution_log` + `_apply_accepted_proposals`
+   - el sandbox/snapshot/rollback protege la materializacion del cambio aceptado
+   - no dupliques ese mecanismo en deep sleep ni en el runner de auditoria
+4. Lanza la verificacion empirica de todos los items en paralelo:
+   - `grep + read` del codigo
+   - SQL/schema real
+   - AST/tests/imports/logs cuando aplique
+   - asume FP hasta que la evidencia lo contradiga
+5. Clasifica cada item:
+   - `real_gap`
+   - `casi_fp`
+   - `fp`
+6. Ordena solo los `real_gap` por riesgo/blast radius y ejecutalos con worktree aislado si tocan core.
+7. Por cada `real_gap`:
+   - `guard_check`
+   - `track`
+   - branch propia
+   - implementacion minima
+   - tests adyacentes
+   - PR + auto-merge squash
+   - seguir al siguiente sin esperar CI salvo bloqueo real
+8. Para `fp` o `casi_fp`, captura learning/patron reusable en vez de reimplementar.
+9. Cierra la fase con evidencia real: PRs, tests, merge status y resultados de verificacion.
+
+## Gotchas
+- Learning #198: no confundas "como trabaja NEXO" con "que puede aplicar evolution_apply". Lo primero ya esta resuelto: autonomia total.
+- `apply_findings.py` ya stagea `code_change` en `evolution_log`; `nexo-evolution-run.py` ya consume `accepted` con sandbox/snapshot/rollback. Si el item pide eso, primero verifica si ya existe.
+- En Fase 1+2 la auditoria automatica sobreestimo ~70% de gaps. Si no hay evidencia dura, no abras codigo.

package/src/skills/run-nexo-audit-phase/skill 2.json

@@ -0,0 +1,59 @@
+{
+  "id": "SK-RUN-NEXO-AUDIT-PHASE",
+  "name": "Run NEXO Audit Phase",
+  "description": "Workflow para ejecutar una fase de auditoria de NEXO con autonomia total y verificacion empirica. Cubre el patron repetido de decidir el scope de evolution_apply y arrancar una tanda de items sin checkpoints manuales.",
+  "level": "published",
+  "mode": "guide",
+  "source_kind": "core",
+  "execution_level": "none",
+  "approval_required": false,
+  "tags": [
+    "nexo",
+    "audit",
+    "evolution",
+    "sandbox",
+    "verification",
+    "core"
+  ],
+  "trigger_patterns": [
+    "evolution_apply sandbox scope",
+    "fase 2 item 1",
+    "arrancar verificacion empirica",
+    "ejecutar fase de auditoria nexo",
+    "audit phase nexo",
+    "7 items audit"
+  ],
+  "steps": [
+    "Abrir goal, workflow y task antes de tocar la auditoria; resolver repo/runtime real, DB real, tests y estado git antes de interpretar el informe.",
+    "Fijar la regla de autonomia: NEXO hace branches, PRs, merge y progreso periodico; no pedir checkpoints uno-a-uno a Francisco para trabajo mecanico.",
+    "Para `evolution_apply`, separar dos planos: el sandbox es para materializar/aplicar cambios aceptados con snapshot/rollback; no es un freno para el modo de trabajo autonomo del agente.",
+    "Lanzar verificacion empirica de TODOS los items en paralelo: grep+read, SQL/schema real, AST/tests, logs. Partir de la hipotesis de FP hasta tener evidencia.",
+    "Clasificar cada item en `real_gap`, `casi_fp` o `fp` y ordenar solo los reales por blast radius/riesgo.",
+    "Si hay que tocar core, usar worktree aislado; por item real: guard_check -> track -> branch -> implement -> tests adyacentes -> PR -> auto-merge squash.",
+    "Para items FP o casi-FP, capturar learning o ajustar el patron reusable en vez de reimplementar.",
+    "Cerrar con evidencia de PRs, tests y merge status reales; no usar diarios o workflow text como sustituto."
+  ],
+  "gotchas": [
+    "No pedir aprobacion manual a Francisco para cada PR: learning #198 confirma autonomia total con transparencia y reportes periodicos.",
+    "No duplicar el sandbox de evolution en otros sitios: el apply de cambios aceptados ya reutiliza evolution_log + sandbox/snapshot/rollback.",
+    "El ratio historico de FPs en esta clase de auditoria es alto; si no hay evidencia concreta, el item no se toca."
+  ],
+  "params_schema": {
+    "audit_file": {
+      "type": "string",
+      "required": true
+    },
+    "phase_label": {
+      "type": "string",
+      "required": false,
+      "default": ""
+    },
+    "repo_path": {
+      "type": "string",
+      "required": false,
+      "default": ""
+    }
+  },
+  "command_template": {},
+  "stable_after_uses": 5
+}

package/src/skills/run-nexo-core-fix-cycle/guide 2.md

@@ -0,0 +1,17 @@
+# Run NEXO Core Fix Cycle
+
+Usa esta skill cuando haya que implementar y verificar un grupo pequeño de fixes del core de NEXO sin improvisar el plano ni repetir siempre la misma fase de descubrimiento y test.
+
+## Steps
+1. Fija primero el plano: repo público `nexo`, runtime instalado `~/.nexo` y claims/documentación pública. No mezcles esos tres mundos.
+2. Abre `nexo_task_open(...)` y `nexo_workflow_open(...)` antes de tocar código. Si el fix es de acción, pasa también por `nexo_cortex_decide(...)`.
+3. Ejecuta la skill con `areas` ajustadas al fix. El helper te devuelve el mapa de archivos y corre la batería de tests focalizada para `protocol`, `plane`, `guard`, `cortex` y/o `release`.
+4. Implementa el cambio mínimo defendible solo en la superficie correcta. Si el problema es producto, se arregla en el repo; no en `~/.nexo`.
+5. Reejecuta la skill para revalidar el clúster exacto de tests tocado por el fix.
+6. Cierra con `nexo_task_close(...)` y evidencia real. Si hubo edición real, deja `change_log` y captura learning si cambió una regla canónica.
+
+## Gotchas
+- No uses diary, workflow text o intuición como sustituto de git/tests/runtime reales.
+- Si el fix toca doctor o claims públicos, fija el `plane` explícito antes de ejecutar diagnósticos.
+- Si el fix toca release o runtime update, usa la vía oficial (`nexo update`, doctor, skill de release final) y no scripts laterales.
+- Si el helper no encuentra un área, añade la superficie nueva de forma explícita en la skill en vez de seguir repitiendo grep manual disperso.

package/src/skills/run-nexo-core-fix-cycle/script 2.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+AREA_MAP = {
+    "protocol": {
+        "files": [
+            "src/plugins/protocol.py",
+            "src/db/_protocol.py",
+            "src/db/__init__.py",
+            "tests/test_protocol.py",
+        ],
+        "tests": [
+            "tests/test_protocol.py",
+        ],
+    },
+    "plane": {
+        "files": [
+            "src/doctor/orchestrator.py",
+            "src/plugins/doctor.py",
+            "src/server.py",
+            "tests/test_doctor.py",
+        ],
+        "tests": [
+            "tests/test_doctor.py",
+        ],
+    },
+    "guard": {
+        "files": [
+            "src/hook_guardrails.py",
+            "tests/test_hook_guardrails.py",
+        ],
+        "tests": [
+            "tests/test_hook_guardrails.py",
+        ],
+    },
+    "cortex": {
+        "files": [
+            "src/plugins/cortex.py",
+            "tests/test_cortex_decisions.py",
+        ],
+        "tests": [
+            "tests/test_cortex_decisions.py",
+        ],
+    },
+    "release": {
+        "files": [
+            "scripts/verify_release_readiness.py",
+            "src/skills/run-release-final-audit/script.py",
+            "tests/test_verify_release_readiness.py",
+            "tests/test_release_readiness_baseline.py",
+        ],
+        "tests": [
+            "tests/test_verify_release_readiness.py",
+            "tests/test_release_readiness_baseline.py",
+        ],
+    },
+}
+
+
+def _is_repo_root(candidate: Path) -> bool:
+    return (
+        (candidate / "package.json").is_file()
+        and (candidate / "src" / "server.py").is_file()
+        and (candidate / "tests").is_dir()
+    )
+
+
+def _normalize_candidate(raw: str | Path) -> Path:
+    candidate = Path(raw).expanduser().resolve()
+    if candidate.is_file():
+        candidate = candidate.parent
+    if candidate.name == "src" and (candidate / "server.py").is_file():
+        candidate = candidate.parent
+    return candidate
+
+
+def _resolve_repo_root_from_atlas() -> Path | None:
+    homes = []
+    env_home = os.environ.get("NEXO_HOME", "").strip()
+    if env_home:
+        homes.append(Path(env_home).expanduser())
+    homes.extend((Path.home() / ".nexo", Path.home() / "claude"))
+
+    seen = set()
+    for home in homes:
+        key = str(home)
+        if key in seen:
+            continue
+        seen.add(key)
+        atlas_path = home / "brain" / "project-atlas.json"
+        if not atlas_path.is_file():
+            continue
+        try:
+            payload = json.loads(atlas_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            continue
+        nexo = payload.get("nexo") if isinstance(payload, dict) else None
+        locations = nexo.get("locations") if isinstance(nexo, dict) else None
+        source = locations.get("mcp_server", "") if isinstance(locations, dict) else ""
+        if not isinstance(source, str) or not source.strip():
+            continue
+        candidate = _normalize_candidate(source)
+        if _is_repo_root(candidate):
+            return candidate
+    return None
+
+
+def _resolve_repo_root(explicit_root: str = "") -> Path:
+    if explicit_root.strip():
+        candidate = _normalize_candidate(explicit_root)
+        if _is_repo_root(candidate):
+            return candidate
+
+    env_code = os.environ.get("NEXO_CODE", "").strip()
+    if env_code:
+        candidate = _normalize_candidate(env_code)
+        if _is_repo_root(candidate):
+            return candidate
+
+    cwd = Path.cwd().resolve()
+    for candidate in (cwd, *cwd.parents):
+        if _is_repo_root(candidate):
+            return candidate
+
+    atlas_repo = _resolve_repo_root_from_atlas()
+    if atlas_repo is not None:
+        return atlas_repo
+
+    script_root = Path(__file__).resolve().parents[3]
+    if _is_repo_root(script_root):
+        return script_root
+    return script_root
+
+
+def _parse_bool(raw: str, default: bool) -> bool:
+    text = (raw or "").strip().lower()
+    if not text:
+        return default
+    if text in {"1", "true", "yes", "on"}:
+        return True
+    if text in {"0", "false", "no", "off"}:
+        return False
+    raise SystemExit(f"[core-fix-cycle] invalid boolean: {raw}")
+
+
+def _normalize_areas(raw: str) -> list[str]:
+    text = (raw or "protocol,plane").replace("+", ",")
+    parts = [item.strip().lower() for item in text.split(",") if item.strip()]
+    if not parts:
+        return ["protocol", "plane"]
+    unknown = [item for item in parts if item not in AREA_MAP]
+    if unknown:
+        raise SystemExit(
+            f"[core-fix-cycle] unknown area(s): {', '.join(unknown)}. Expected one of: {', '.join(sorted(AREA_MAP))}"
+        )
+    seen = set()
+    ordered = []
+    for item in parts:
+        if item in seen:
+            continue
+        seen.add(item)
+        ordered.append(item)
+    return ordered
+
+
+def _env(root: Path, nexo_home: str) -> dict[str, str]:
+    env = os.environ.copy()
+    src_path = str(root / "src")
+    existing_pythonpath = env.get("PYTHONPATH", "").strip()
+    env["PYTHONPATH"] = (
+        f"{src_path}{os.pathsep}{existing_pythonpath}" if existing_pythonpath else src_path
+    )
+    env["NEXO_CODE"] = src_path
+    env["PYTEST_DISABLE_PLUGIN_AUTOLOAD"] = "1"
+    if nexo_home.strip():
+        env["NEXO_HOME"] = str(Path(nexo_home).expanduser())
+    return env
+
+
+def _command_succeeds(cmd: list[str], *, env: dict[str, str], root: Path) -> bool:
+    result = subprocess.run(
+        cmd,
+        cwd=root,
+        env=env,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return result.returncode == 0
+
+
+def _resolve_python(root: Path, env: dict[str, str]) -> str:
+    candidates = []
+    override = os.environ.get("NEXO_RELEASE_PYTHON", "").strip()
+    if override:
+        candidates.append(override)
+
+    for name in ("python3", "python"):
+        path = shutil.which(name)
+        if path:
+            candidates.append(path)
+
+    candidates.append(sys.executable)
+
+    seen = set()
+    for candidate in candidates:
+        if not candidate or candidate in seen:
+            continue
+        seen.add(candidate)
+        if _command_succeeds([candidate, "-m", "pytest", "--version"], env=env, root=root):
+            return candidate
+
+    raise SystemExit(
+        "[core-fix-cycle] no Python interpreter with pytest available. "
+        "Set NEXO_RELEASE_PYTHON or install pytest in the active runtime."
+    )
+
+
+def _run(cmd: list[str], *, env: dict[str, str], root: Path) -> None:
+    print(f"[core-fix-cycle] $ {' '.join(cmd)}")
+    result = subprocess.run(cmd, cwd=root, env=env)
+    if result.returncode != 0:
+        raise SystemExit(result.returncode)
+
+
+def main() -> int:
+    areas = _normalize_areas(sys.argv[1] if len(sys.argv) > 1 else "protocol,plane")
+    run_tests = _parse_bool(sys.argv[2] if len(sys.argv) > 2 else "true", True)
+    repo_root = _resolve_repo_root(sys.argv[3] if len(sys.argv) > 3 else "")
+    nexo_home = sys.argv[4] if len(sys.argv) > 4 else ""
+    env = _env(repo_root, nexo_home)
+
+    files: list[str] = []
+    tests: list[str] = []
+    for area in areas:
+        for path in AREA_MAP[area]["files"]:
+            if path not in files:
+                files.append(path)
+        for path in AREA_MAP[area]["tests"]:
+            if path not in tests:
+                tests.append(path)
+
+    print(f"[core-fix-cycle] repo_root={repo_root}")
+    print(f"[core-fix-cycle] areas={','.join(areas)}")
+    print("[core-fix-cycle] file-map:")
+    for path in files:
+        label = "OK" if (repo_root / path).exists() else "missing"
+        print(f"[core-fix-cycle]   - {path} [{label}]")
+
+    if not run_tests:
+        print("[core-fix-cycle] tests skipped")
+        print("[core-fix-cycle] OK")
+        return 0
+
+    existing_tests = [path for path in tests if (repo_root / path).is_file()]
+    if not existing_tests:
+        print("[core-fix-cycle] no tests found for selected areas")
+        print("[core-fix-cycle] OK")
+        return 0
+
+    python_bin = _resolve_python(repo_root, env)
+    print(f"[core-fix-cycle] python={python_bin}")
+    _run([python_bin, "-m", "pytest", "-q", *existing_tests], env=env, root=repo_root)
+    print("[core-fix-cycle] OK")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skills/run-nexo-core-fix-cycle/skill 2.json

@@ -0,0 +1,58 @@
+{
+  "id": "SK-RUN-NEXO-CORE-FIX-CYCLE",
+  "name": "Run NEXO Core Fix Cycle",
+  "description": "Mapea las superficies core impactadas y ejecuta la verificación focalizada para ciclos pequeños de fixes de NEXO sin mezclar repo público, runtime y claims no verificados.",
+  "level": "published",
+  "mode": "hybrid",
+  "source_kind": "core",
+  "execution_level": "read-only",
+  "approval_required": false,
+  "tags": [
+    "nexo",
+    "core",
+    "fix",
+    "protocol",
+    "plane",
+    "verification"
+  ],
+  "trigger_patterns": [
+    "dos fixes core nexo",
+    "core fix cycle",
+    "enforcement protocolario",
+    "plano antes del diagnostico",
+    "ciclo fix core nexo"
+  ],
+  "params_schema": {
+    "areas": {
+      "type": "string",
+      "required": false,
+      "default": "protocol,plane"
+    },
+    "run_tests": {
+      "type": "boolean",
+      "required": false,
+      "default": true
+    },
+    "repo_root": {
+      "type": "string",
+      "required": false,
+      "default": ""
+    },
+    "nexo_home": {
+      "type": "string",
+      "required": false,
+      "default": ""
+    }
+  },
+  "command_template": {
+    "argv": [
+      "{{file_path}}",
+      "{{areas}}",
+      "{{run_tests}}",
+      "{{repo_root}}",
+      "{{nexo_home}}"
+    ]
+  },
+  "executable_entry": "script.py",
+  "stable_after_uses": 5
+}

package/src/skills/run-release-final-audit/guide 2.md

@@ -0,0 +1,16 @@
+# Run Release Final Audit
+
+Use this before claiming a release/publication is closed when you need a live check that smoke, release contract, public surfaces, runtime update/doctor, and protocol closeout still align.
+
+## Steps
+1. Run the skill with defaults to audit the current package version. It auto-resolves `release-contracts/v{version}.json` and `scripts/run_vX_Y_smoke.py` when present.
+2. Keep `contract="auto"` and `require_contract_complete=true` for the real final gate. Set `contract="none"` only for pre-contract repo checks.
+3. For the real post-publish closeout, set `final_closeout=true` and pass the release `protocol_task_id` so the audit also verifies GitHub Release, npm, `nexo update`, runtime doctor, `change_log`, and `task_close`.
+4. Treat `ci=true` as repo-only. The last live audit must stay outside CI because `final_closeout` expects a live runtime and a real closed task.
+
+## Gotchas
+- A missing auto-resolved contract is a real blocker for the final release audit.
+- Smoke is version-line scoped. If no runner exists, the skill reports the skip explicitly instead of pretending it ran.
+- The script is read-only except for the optional official `nexo update` step during `final_closeout`; it still does not bump versions, tag, publish, or edit website worktrees.
+- `final_closeout` is intentionally stricter than the repo-only readiness pass: it fails if the release task was not closed with evidence or if its `change_log` row is missing.
+- If the touched area includes bootstrap, startup, or public claims, finish with the manual watchpoints in `docs/client-parity-checklist.md`.