tylluan

Imported from Forja-orca/tylluan (AGENTS.md). Install upstream with npx skills add Forja-orca/tylluan. Copyright stays with the author.

Tylluan v0.17.1 — Agent Instructions (Codex / OpenCode)

Este archivo es leído automáticamente por agentes OpenCode/Codex al conectar (Deep, Mimo, cualquier futuro agente en ese runtime). Si está desactualizado, TODO agente de esa clase arranca con información falsa desde el primer segundo — no es un detalle cosmético. Confirmado 2026-07-28: este archivo llevaba meses con versión, milestones y flota incorrectos mientras el equipo lo usaba a diario.

Regla fundacional

Tylluan es un producto público MIT. Este workspace (E:\tylluan) es autocontenido: no depende de ningún otro repositorio ni framework interno para funcionar, compilar, o pasar sus tests.

• Trabaja exclusivamente dentro de este workspace.
• Si necesitas portar un patrón de otro proyecto, adáptalo e impleméntalo limpio aquí — nunca copies código ni referencies rutas de otros repositorios locales.

Regla obligatoria — sincroniza ANTES de reportar nada (2026-07-30)

Causa raíz de un incidente real: un agente nuevo auditó la conexión del proyecto y reportó 4 hallazgos como si estuvieran abiertos — los 4 ya estaban cerrados en main, en commits de minutos/horas antes. Su checkout local nunca se sincronizó contra origin/main al empezar la sesión, así que trabajó (y reportó) sobre un estado del repo que ya no existía. No es un caso aislado: este mismo AGENTS.md ya había estado meses desactualizado por la misma razón de fondo (nadie fuerza una sincronización al arrancar).

Regla, sin excepción, antes de escribir un solo hallazgo, PR o mensaje de "esto está roto":

git fetch origin
git log -1 origin/main --oneline   # commit real de main
git log -1 HEAD --oneline          # tu commit local

Si difieren, git pull (o el equivalente de tu runtime) antes de seguir. Un hallazgo sobre código que ya cambió no es un hallazgo — es ruido que hace perder tiempo real al resto del equipo verificándolo. Si tu runtime no te deja sincronizar automáticamente, dilo explícitamente en tu primer mensaje ("mi checkout puede estar desactualizado, no lo he podido sincronizar") en vez de reportar con la confianza de quien sí lo hizo.

Environment

Platform: Windows 11. Bash disponible solo para operaciones read-only (git, cargo check/test).
Para arrancar procesos: proporcionar el comando al usuario, no ejecutarlo vía Bash.

Arrancar kernel:

tylluan-cli start
# o desde source:
cargo run -p tylluan-cli -- start

Health check: curl http://127.0.0.1:47004/health
Dashboard dev: cd dashboard && pnpm dev → http://localhost:5173

Estado actual — v0.17.1 (v0.17.0 tagged 2026-08-23; v0.17.1 corta los fixes de seguridad e instalador del 2026-10-05/12)

Tests: 1053 lib tests (kernel) + 74 (tylluan-link) + 12 (tylluan-fsrs) = 1139 en verde — verificar con cargo test -p tylluan-kernel --lib antes de fiarte de cualquier cifra escrita aquí, el número real cambia cada ciclo (y scripts/check_test_count.sh ya valida esta cifra en CI). HEAD commit real: consultar git log --oneline -1, o curl http://127.0.0.1:47004/health para el commit que el kernel EN EJECUCIÓN tiene cargado (puede ir por detrás de main si nadie ha reconstruido tras el último cambio en .rs).

Cerrado en v0.17.0 (2026-08-24; trabajo del 2026-08-11 al 2026-08-14): dos rondas de auditoría externa cerradas el mismo día cada una — RCE crítico de P2P (4674f84) con verificación real de peer añadida después (ebbc998, Ed25519↔X25519), ACL rediseñado fail-closed (09b9668), ASI06 cerrado con gate de escritura de 2 capas para tylluan_remember (2bd0416). FrictionStore con path inyectable, split de api_v1.rs (3114→3 archivos). A2A F1-F4 completo: cliente outbound real verificado contra el SDK oficial, exposición REST/intent con ACL, streaming SSE, hardening (3f4ce1e). Dashboard: identidad visual soberana en 4 fases verificadas (paleta con nombre propio, tipografía self-hosted, WCAG AA real, piloto de foco de teclado). Ver CHANGELOG.md, sección [0.17.0], para el detalle completo.

Cerrado en v0.16.0 (2026-08-11): M39 (adopción MCP 2026-07-28: stateless core verificado en vivo, Tasks con guards reales, MCP Apps con manifiestos reales) y M40 (Tylluan como capa de continuidad/confianza/acción, 8 fases) ambos completos — condición explícita de José para el release. 3 bugs reales encontrados en vivo y cerrados end-to-end, incluido el cuelgue histórico de Qwen Desktop en modo SSE (causa raíz: sse_handler descartaba los headers reales del cliente). Circuito CoherenceGate→dataset fase 1+2: ejemplos estructurados A/B con ground truth real vía el Signal Loop de ADR-011, nada entrenado todavía.

Cerrado en v0.15.0 (2026-07-30): auditoría completa de conexión real (Deep/Mimo/Claude) — 5 guilds con IPC al puerto equivocado, escrituras a SilvaDB sin embedding, paneles de dashboard con datos falsos; cifrado obligatorio Noise NK para gossip de producción (antes en texto plano); CoherenceGate Layer 4 híbrido wireado en vivo, modo observación; [guilds.v2] activó 13 guilds más + test estructural anti-drift; crash de visión por TDR de GPU en Windows, causa raíz confirmada y arreglada.

Milestones completados

✅ significa implementado y con tests. No significa activo por defecto ni útil en producción: las filas con nota entre paréntesis se corrigieron el 2026-10-14 contra el código.

Completado en v0.11.0

Completado en v0.12.0

Arquitectura invariante (CONTRACT-01)

1. 6 sovereign tools exactamente: tylluan_do, tylluan_remember, tylluan_recall, tylluan_think, tylluan_graph, tylluan_decide (la sexta, tylluan_decide, entró por enmienda formal ADR-021, 2026-10-16). all_tools() en server.rs DEBE filtrar a estas 6 y nada más. NUNCA añadir herramientas nuevas aquí sin una enmienda formal de CONTRACT-01 aprobada por José.
2. Embeddings a 1024 dimensiones — vector_dimensions = 1024. Default actual mxbai-embed-large (1024d, desde 2026-09-30; default_embedding_model() en config.rs). BGE-M3 sigue soportado. NUNCA reducir a 768. Nota (2026-10-14): embeddings.rs también acepta bge-small/minilm (384d) y nomic-embed-text (768d) y el perfil clinic usa 384d; mezclar dimensiones en una misma base rompe la búsqueda vectorial. Si esa flexibilidad debe existir es una decisión de arquitectura pendiente, no un detalle de configuración.
3. Headless-first: kernel sin UI propia. Dashboard React en /dashboard.
4. Puerto único: tylluan-nexus escucha en :47004 directamente. SIN proxy de zero-downtime — un solo proceso kernel.
5. MIT soberanía: sin dependencias cloud en el critical path.
6. Degree penalty (no boost): local_query_graph usa pr_score / (1 + deg * 0.1) — penaliza hubs genéricos. El boost (*) fue un bug corregido en v0.10.0.

Archivos clave

Validación estándar

cargo check -p tylluan-kernel
cargo test -p tylluan-kernel --lib 2>&1 | tail -3
# Esperado: 1027 lib tests passing (cifra exacta: scripts/check_test_count.sh)

cargo test -p tylluan-link --all-targets 2>&1 | Select-String "test result"
# Esperado: 74 link tests passing

# tylluan-evals es un harness de benchmark: sus tests (paired_eval) no cuentan en el total de 1127.

Reglas críticas

• NUNCA vector_dimensions = 768 — rompe todos los embeddings
• NUNCA host = "0.0.0.0" + dev_mode = true juntos (LAN RCE)
• NUNCA tokens en archivos trackeados — solo en .tylluan-token (gitignored)
• NUNCA iniciar procesos vía Bash (AV bloquea spawning en Windows)
• NUNCA reducir timeouts para guilds de inferencia (los embeddings en CPU pueden tardar segundos; no hay medida publicada por modelo)
• NUNCA cambiar el degree bias de vuelta a multiplicación — el / (1 + deg * 0.1) es correcto

Flota de agentes

Reglas de asignación:

• Rust / crates/ → Deep (briefing previo con DoD y zonas excluidas)
• Dashboard / UI → Mimo o Antigravity, en pasos pequeños verificados uno a uno, nunca un rediseño completo de golpe
• Research web / papers / repos → Qwen Desktop
• Orquestación / docs / arbitraje → Claude Code

Disciplina no negociable para cualquier agente de esta flota (aprendida a base de incidentes reales, 2026-07-28):

1. Nunca afirmar "cerrado"/"funciona" sin verificar tú mismo (leer el código, correr el build/test real, probar en vivo). cargo check/cargo test NO corren clippy -D warnings — CI sí; corre cargo clippy -p tylluan-kernel -- -D warnings tú mismo antes de dar un cambio Rust por listo.
2. Un guild Python nuevo necesita un descriptor en router/catalog.rs y estar registrado: en LAZY_GUILDS (registry/guild_list.rs) o en always_on de tylluan.toml. Si falta el segundo paso, tylluan_do responde "Unknown guild" en runtime; los tests test_every_guild_file_is_in_catalog y test_lazy_or_always_on_guilds_are_registered lo vigilan. No basta con crear el .py.
3. Dashboard: pnpm, nunca npm (dos lockfiles divergentes rompieron dependencias en producción, 2026-07-28); solo dashboard/pnpm-lock.yaml está versionado. Excepción: el paquete compartido packages/tylluan-ui-core se construye con npm en CI.
4. Si dos agentes tocan piezas complementarias (un endpoint + quien lo consume), acordar el esquema EXACTO (nombres de tabla/campo, puertos) en Coloquio antes de escribir código — pasó 2 veces el mismo día no hacerlo y hubo que arreglar el desajuste después.
5. Nunca dejar trabajo sin commitear acumulándose — commits pequeños y verificados, no todo junto al final.
6. Nunca atribuir una decisión a José que no diera — si actúas por iniciativa propia, dilo así.
7. Todo commit lleva la pregunta de no-depredación respondida (ADR-013): corre scripts/check_no_predation.sh tras commitear y antes de reportar el cambio como verificado; tocar transport/, guilds/, integrations/ o tylluan*.toml exige sección ## Impact en el mensaje del commit.
8. Cada agente trabaja SOLO en su propio worktree. Nunca edites ni comitees en el checkout compartido: es lo que activa la puerta anti-depredación (ADR-013, "WIP ajeno") y ya costó incidentes repetidos.
9. Solo Claude Code comitea y empuja a origin/main. El resto entrega diff sin commitear más un informe; el pre-push ejecuta scripts/verify.sh (unos 10 minutos) y nunca se salta con --no-verify.

Perfiles declarativos (M19-P5): ver ADR-009 — .tylluan/agents.toml es el contrato máquina-legible que el kernel carga al arrancar (agent_id → rol ACL). Este archivo (AGENTS.md) sigue siendo la documentación humana; no se parsea.

Protocolo de actualización de documentación post-milestone

Regla: ningún milestone se da por cerrado hasta que estos archivos reflejen el estado real. La doc que miente genera trabajo fantasma para el siguiente agente.

Al cerrar cualquier milestone, el agente que lo cierra ejecuta este checklist antes de anunciar "cerrado" en Coloquio:

0. Puertas de documentación — scripts/check_docs_reality.sh (rutas, puerto, versión, recuento de tests y de guilds) y scripts/check_doc_links.py (enlaces relativos) corren en verify.sh y en CI; si fallan, la documentación miente.
1. STATUS.md — actualizar versión, tabla de tests, "What works" con lo que el milestone entregó. Fuente de verdad técnica: lo obsoleto se borra, no se acumula.
2. ROADMAP.md — mover el milestone a cerrado con fecha y commit hash.
3. docs/internal/PROJECT.map / OPERATIONS.map — solo si el milestone cambió arquitectura o invariantes.
4. SPEC.md — solo si cambió alcance, audiencias, o cerró un ítem de la tabla "documentación que falta".
5. CHANGELOG.md — entrada nueva por milestone/release, no acumular cambios sin registrar.
6. AGENTS.md (este archivo) — si cambió la flota de agentes o sus reglas de asignación.

Quién verifica: el Tech Lead (Claude Code) confirma que estos puntos están al día antes del visto bueno final — contrastado contra el archivo real, no solo el reporte del agente que cerró el milestone.

Por qué existe esta regla: en la sesión del 2026-07-10 se encontró STATUS.md con 2 milestones de retraso (M22 y M23-P1 cerrados sin documentar). Este protocolo existe para que no se repita.

Escalada (2026-07-28): este mismo archivo (AGENTS.md) llevaba meses reportando v0.10.0 mientras el repo estaba en v0.13-0.14, con la flota de agentes desactualizada. Como es el archivo que OpenCode/Codex carga automáticamente al conectar cualquier agente, la desactualización no es solo ruido documental — es contexto falso heredado por cada agente nuevo desde el primer segundo, coincidiendo con el hallazgo de investigación del mismo día sobre degradación de seguridad en el arranque en frío de un agente (arXiv:2606.07867). Revisar este archivo específicamente en cada cierre de milestone, no solo STATUS.md.