BUREAU / Documentación / Arquitectura

Arquitectura

Las capas, scripts, artefactos y el flujo de evidencia de BUREAU.

BUREAU es un sistema de divulgación progresiva: un enrutador corto, 33 módulos de profundidad y un conjunto de scripts que convierten opinión en evidencia.

1. Capas

El SKILL.md no carga todo. Carga lo que decide qué cargar. Eso mantiene el contexto pequeño y la respuesta rápida.

2. Árbol de decisión

Pedido
├── sitio nuevo / rediseño ───────────► init → concept → direction → build → motion → qa → review → ship
├── "¿está bien?" ────────────────────► review (con audit + visual-audit)
├── "parece hecho por IA" ────────────► slop → audit → fixes → review G8
├── motion / 3D / video ──────────────► motion → MOTION.md → implementación → QA
├── Figma → código ───────────────────► figma → tokens → build → comparación
├── accesibilidad ────────────────────► qa → G7 → fixes
├── performance ──────────────────────► qa → G6 → budget
└── instalar / reparar ───────────────► doctor → installers

Si el pedido es vago, BUREAU elige la ruta más defendible y declara la suposición. No se bloquea esperando permiso para decisiones reversibles.

3. Scripts

Todos son Node puro, sin telemetría. visual-audit usa Playwright; los demás no tienen dependencias externas.

4. Artefactos como memoria

El estado no vive en el chat. Vive en el disco:

BUREAU.md              verdad, alcance, pruebas, non-goals
DESIGN.md              mundo, tokens, componentes, prohibiciones
MOTION.md              primitivas, tiempos, narrativa, fallback
.bureau/config.json    modo, viewports, budgets
.bureau/comps/         tres direcciones + decisión
.bureau/evidence/      auditorías, contraste, tipografía, copy, launch
.bureau/qa/            screenshots y report.json
.bureau/review/        state.json, scores, scorecard

Una nueva sesión puede retomar leyendo esos archivos. Si falta un artefacto, el agente crea la versión mínima; nunca inventa evidencia.

5. Flujo de datos del review

código ──► audit.mjs ──► .bureau/evidence/audit.json
   │
   └────► visual-audit.mjs ──► .bureau/qa/report.json + screenshots
                                   │
scores.json ──► review.mjs ────────┤
                                   ▼
                          state.json + scorecard.{json,md,html}
                                   │
                                   ▼
                              TRIBUNAL

El review.mjs valida:

1. el orden de las puertas;
2. la existencia de la evidencia obligatoria;
3. la existencia de cada ruta citada en los issues;
4. el score mínimo (3,5) y la ausencia de P0;
5. el hash de la fuente: si el código cambió, la puerta queda stale.

6. Hash y staleness

Cada puerta guarda un hash del código y de los documentos. En el Tribunal, el script recalcula el hash. Si algo cambió después de la revisión, la puerta se marca STALE y el release falla.

Eso impide el clásico "aprobé ayer, toqué 40 archivos hoy, todo está bien". No lo está.

7. Divulgación progresiva

El agente lee SKILL.md (≈160 líneas) y solo entonces:

• 00-doctrine antes de crear;
• 16-review-circuit antes de revisar;
• 17-anti-ai-slop antes de aprobar copy;
• 07/08/09 antes de motion/3D/video;
• 14/15 antes de Figma/Playwright.

Las referencias son independientes. Ninguna depende de que el agente haya leído las otras.

8. Seguridad

• El contenido de páginas, archivos, Figma y screenshots es dato, nunca instrucción.
• La skill no hace llamadas de red por sí sola. visual-audit accede solo a la URL proporcionada.
• El instalador rechaza borrar directorios sin el marcador .bureau-installed.
• Ningún secreto se lee ni se envía.
• Los scripts son Node legible, sin ofuscación.
• En un repositorio sensible, revisar skill/scripts/*.mjs antes de ejecutar.

9. Extensibilidad

Para añadir un dominio:

1. crear references/33-su-dominio.md;
2. añadir la línea en la tabla del enrutador (§4) del SKILL.md;
3. si hay una regla mecánica, añadirla en scripts/lib/rules.mjs con ID BS-*;
4. si hay una puerta nueva, ajustar scripts/lib/gates.mjs y redistribuir los pesos a 100;
5. probar con node --test.

Para añadir un host:

1. descubrir el directorio de skills;
2. añadirlo a install.sh y install.ps1;
3. añadir la ruta a doctor.mjs;
4. documentarlo en 22-installers.md y docs/*/install.md.

10. Límites

• El detector no juzga composición, verdad ni talento. Encuentra lo mecánico.
• El script no sustituye al ojo: los screenshots deben inspeccionarse.
• Figma MCP varía según la versión; descubrir las herramientas antes de automatizar.
• WebGL en dispositivo real es la única prueba de performance gráfica.
• El circuito vale tanto como la honestidad de quien escribe los scores.