FND-003: Organización del equipo, gobernanza del proyecto y flujo de contribución

A partir de v0.7.0 · Tipo: Gobernanza · Rev. 16

Referencia canónica · Ratificado por el equipo · Rev. 16 Debate original sobre la gobernanza: #5577 Política de seguimiento de líneas de trabajo y gobernanza de etiquetas: #6808

Una nota para el equipo antes de que lean esto.

Los proyectos de software no fracasan porque el código sea malo. Fracasan porque las personas que escriben el código no pueden coordinarse. Las funcionalidades se construyen dos veces. Los errores se pierden. Las buenas ideas se evaporan porque nadie las anotó. Los nuevos colaboradores llegan con ganas de ayudar y no encuentran por dónde empezar. Este RFC trata sobre construir la estructura ligera que previene esos fracasos, no para que el proyecto se sienta organizado, sino para que el equipo pueda avanzar más rápido, con más confianza y con menos fricción. Cada recomendación aquí está elegida específicamente para un equipo de código abierto pequeño, en crecimiento y liderado por estudiantes. Nada de esto requiere un gestor de proyectos, un Scrum Master ni un comité formal.

Historial de revisiones

Tabla de contenidos

1. El problema de coordinación
2. El sistema de tres partes
3. Proyectos de GitHub: El flujo de trabajo
   • 3.6 Carriles de Trabajo y Propiedad del Estado
4. GitHub Discussions: debate de la comunidad y traspaso
   • 4.5 Gestión de Discusiones y Transición de Discord a GitHub
5. Capas de equipo y autoridad de contribución
6. CODEOWNERS y protección de ramas
   • 6.4 Cumplimiento Arquitectónico: Revisión Humana, Soporte de IA
7. Plantillas de problemas
8. El ciclo de gobernanza de RFC
9. Taxonomía de etiquetas
10. Definición de Hecho
11. Automatización
12. Implementación por fases

1. El problema de la coordinación

Cada proyecto sin un sistema de coordinación intencional desarrolla uno accidental. El sistema accidental en la mayoría de los proyectos de código abierto se ve así:

• Las ideas viven en la cabeza de alguien o en un mensaje de chat que se desplaza fuera de la pantalla.
• Los problemas se acumulan en el rastreador sin prioridad, sin responsable y sin una definición clara de “terminado”.
• Los colaboradores abren PRs por cosas que nadie pidió, o piden ayuda y no reciben respuesta.
• El equipo trabaja de forma reactiva: quien grita más fuerte recibe atención, lo que se rompe se arregla, y nada se planifica con más de una semana de antelación
• Las decisiones arquitectónicas se toman en los comentarios de las PR y nunca se registran en ningún lugar.

Esto no es una crítica al esfuerzo de nadie. Es una descripción de lo que sucede por defecto. La solución no es más proceso. Es el proceso correcto, aplicado al nivel adecuado para el tamaño y la madurez del equipo.

ZeroClaw necesita tres cosas:

1. Un pipeline para convertir ideas en código desplegado, con etapas visibles y puntos de control claros en cada transición
2. Un canal de discusión gestionado para preguntas, ideas, demostraciones y exploración temprana de la comunidad que aún no están listas para el pipeline, sin perderlas ni saturar el trabajo activo
3. Un modelo de gobernanza que define quién puede decidir qué, cómo se toman las decisiones arquitectónicas y cómo crece el equipo

Estas son tres preocupaciones distintas. Confundirlas, poner todo en un solo tablero o depender del chat informal para las decisiones, es lo que crea el caos del que el equipo intenta escapar.

2. El sistema de tres partes

El principio clave: el tablero de Proyecto contiene únicamente el trabajo que el equipo se ha comprometido a considerar. Las primeras discusiones de la comunidad, ideas, preguntas y respuestas, y demostraciones pueden permanecer en Discussions cuando se mantiene el flujo. El trabajo que ha sido evaluado, aceptado y delimitado vive en el Proyecto. Esta distinción es lo que mantiene el tablero útil.

FND-003 es la fuente de gobernanza duradera para la política de líneas de trabajo y la canalización de contribuciones. El RFC #6808 fue la discusión de preparación para las líneas de trabajo orientadas a funciones, la gobernanza de etiquetas, la clasificación de incidencias y el enrutamiento de mantenedores; después de que se promuevan sus segmentos de política, sus reglas duraderas residen en este documento de fundamentos más las páginas operativas de mantenedores enlazadas a continuación. No trates la incidencia del RFC como un documento de gobernanza en competencia después de que su política se haya promovido aquí.

Los detalles operativos viven intencionadamente cerca del flujo de trabajo que los utiliza:

3. Proyectos de GitHub: El flujo de trabajo

3.1 Las etapas del pipeline

El tablero del proyecto tiene un único campo Estado con siete valores. Cada valor es una etapa en la canalización. La secuencia es lineal, pero los elementos pueden moverse hacia atrás:

💡 Idea
    ↓  Gate: Vision alignment check
📋 Backlog
    ↓  Gate: Architecture fit + acceptance criteria
🎯 Defined
    ↓  Gate: Assignee, size, risk tier confirmed
🚧 In Progress
    ↓  Gate: Tests written, CI passing
👀 In Review
    ↓  Gate: Correct reviewer tier approved, docs updated
✅ Done

Más un estado terminal que se puede alcanzar desde cualquier lugar:

🚫 Won't Do  ← explicit decision not to pursue; never silently closed

El estado Won't Do a nivel de tablero es una decisión de cierre duradera. La ortografía actual de las etiquetas de cierre y las reglas del proceso de reemplazo se encuentran en la guía de etiquetas para mantenedores y la guía de sustitución.

3.2 Las preguntas de la puerta

Cada transición tiene una pregunta de control. La pregunta debe responderse con un “sí” antes de que el elemento avance. Este es el tablero del proyecto puesto en práctica: la jerarquía Vision → Architecture → Design → Implementation → Testing → Documentation se convierte en una lista de verificación en cada etapa.

Por qué las puertas explícitas son importantes para un equipo de estudiantes: Sin puertas, las tarjetas se mueven porque alguien siente que ha terminado, no porque “terminado” tenga una definición clara. Esta es la fuente más común de trabajo “terminado” que en realidad no está hecho. Las puertas hacen que la definición sea visible y compartida.

Estas preguntas de control son indicaciones de gobernanza, no otra lista de verificación que duplicar en cada cuerpo de PR o comentario de incidencia. Los formularios operativos residen en los artefactos que los mantenedores ya manejan:

• las plantillas de incidencias recopilan el reporte, el valor para el usuario, la reproducción, el impacto en la arquitectura y las indicaciones de riesgo necesarias para el primer triaje;
• la plantilla de PR recopila los límites del alcance, evidencia de validación, impacto en seguridad/privacidad, compatibilidad, reversión, etiquetas e incidencias vinculadas;
• el flujo de trabajo de PR del mantenedor define el Definition of Ready, el Definition of Done, los carriles de PR y las comprobaciones de fusión;
• la guía de etiquetas define la clasificación duradera, las etiquetas de política de obsolescencia y la secuencia de limpieza;
• el manual del revisor define la recepción, la profundidad de revisión, la clasificación de incidencias, la anulación de la automatización y el mantenimiento de la cola.

Si parece faltar una antigua pregunta de control FND-003, primero revisa esos emplazamientos operativos antes de añadir otra copia aquí.

3.3 Campos personalizados

Crea estos campos en la configuración del proyecto de GitHub:

Sobre el tamaño (tallas de camiseta): Los puntos de historia requieren calibración y datos históricos que el equipo aún no tiene. Las tallas de camiseta son inmediatamente intuitivas y suficientes para un equipo en esta etapa:

Los elementos XL casi siempre deben dividirse antes de entrar en “En progreso”. Si no puedes dividirlo, el diseño no está lo suficientemente completo.

3.4 Vistas

Crea cuatro vistas con nombre en el Proyecto:

Vista 1: Hoja de ruta

• Tipo: Hoja de ruta (cronograma)
• Agrupado por: Hitos
• Campos visibles: Título, Tipo, Tamaño, Componente, Asignado
• Propósito: Público. “Aquí está lo que se viene y cuándo.” Comparte este enlace en el README y con la comunidad. Mantenlo actualizado.

Vista 2: Tablero

• Tipo: Tablero (Kanban)
• Columnas: Valores del campo de estado
• Filtrado a: Solo la versión actual
• Campos visibles: Título, Asignado, Tamaño, Nivel de riesgo
• Propósito: Visibilidad del trabajo diario. ¿En qué está trabajando todo el equipo en este momento? ¿Qué está bloqueado?

Vista 3: Backlog

• Tipo: Tabla
• Ordenado por: Prioridad (descendente), luego Tamaño (ascendente)
• Filtrado por: Estado = Backlog o Definido
• Campos visibles: Título, Tipo, Prioridad, Tamaño, Componente, Hito, Nivel de riesgo
• Propósito: Se utiliza durante las sesiones de refinamiento. ¿Qué es lo que se debe trabajar a continuación? ¿Qué está dimensionado y listo para ser tomado?

Vista 4: Mi trabajo

• Tipo: Tablero
• Filtrado por: Asignado a = @me
• Propósito: Panel personal. Cada colaborador puede ver sus propios elementos sin ruido.

3.5 Elementos anclados

GitHub permite hasta seis problemas fijados por repositorio. Úsalos para una comunicación de alta señal y siempre visible:

1. El RFC activo actual en discusión
2. La función más solicitada por la comunidad (discusión con más votos)
3. El siguiente hito de la versión en el seguimiento de incidencias
4. El índice de good first issue (un issue que enlaza con todos los elementos good first issue actuales)

Los problemas fijados son una promesa para la comunidad: estos son los temas que más importan en este momento. Actualízalos cuando cambien las prioridades.

3.6 Carriles de trabajo y propiedad del estado

La política de carriles de trabajo evita que el tablero, las etiquetas, los PRs y los issues intenten responder la misma pregunta en lugares distintos.

Usa esta división:

Los carriles de PR, las etiquetas de asignación a colaboradores, las etiquetas de exención por inactividad y la migración de etiquetas son conceptos de gobernanza duraderos, pero sus criterios operativos exactos residen en la documentación de los mantenedores. FND-003 define la separación: las etiquetas clasifican el trabajo duradero, los tableros de proyecto planifican el trabajo, el estado nativo de los PR gestiona la revisión y el estado de fusión en vivo, y los issues/RFC preservan las decisiones. El flujo de trabajo de PR para mantenedores define los carriles de PR, la guía de etiquetas define los significados exactos de las etiquetas y las reglas de limpieza, y el manual del revisor define cómo los revisores aplican esas señales durante la clasificación y la revisión. Considera la migración de etiquetas en vivo como una limpieza independiente aprobada por los mantenedores, no como una revisión de PR ordinaria.

Las exenciones de inactividad son excepciones de gobernanza, no escudos de etiqueta permanentes. La política objetivo es que status:no-stale solo sea válido cuando el registro operativo del carril documenta por qué la incidencia está exenta y qué evidencia de enrutamiento visible respalda la siguiente decisión. La documentación para responsables define dónde residen esos hechos y cómo la automatización de inactividad o los barridos de inactividad aplican la regla.

4. GitHub Discussions: Discusión de la comunidad y traspaso

4.1 Carril de Discusiones Mantenidas

Trata GitHub Discussions como un espacio comunitario mantenido. Discussions resulta útil para preguntas, ideas, encuestas, anuncios, presentaciones, demos de proyectos o integraciones, y debates exploratorios que necesitan más permanencia que Discord pero que aún no son trabajo en seguimiento.

Las categorías exactas, las descripciones de categorías y la cadencia de revisión son detalles operativos. Pertenecen a la guía de comunicación para colaboradores y a la documentación del flujo de trabajo del mantenedor, y pueden evolucionar sin necesidad de revisar este documento fundacional.

4.2 Promoción de discusión a trabajo rastreado

Las discusiones no se convierten en trabajo del backlog solo porque exista un hilo. Promueve una discusión cuando produzca un resultado concreto y rastreable. Los ejemplos de desencadenantes orientados a colaboradores se encuentran en Communication.

El destino depende del resultado. Los errores confirmados y los alcances de funcionalidades aceptados se convierten en issues. Las decisiones de arquitectura pasan por el proceso de RFC. Los detalles específicos de un PR se trasladan a comentarios del PR. Las reglas operativas duraderas se mueven a la documentación para mantenedores o colaboradores.

Cierra el ciclo en la Discussion de origen. Si la categoría admite respuestas, marca el resumen o el enlace al trabajo registrado como la respuesta cuando sea apropiado. Si no las admite, agrega un comentario de resumen final con el enlace al issue, RFC, PR o documentación.

4.3 Ideas que no deben esperar a las votaciones

Algunos elementos omiten Discussions y entran directamente en la superficie rastreada:

• Vulnerabilidades de seguridad (a través de informes de seguridad privados, nunca públicos)
• Errores confirmados con pasos de reproducción (ir directamente a la plantilla de informe de errores)
• Elementos de arquitectura aceptados por el RFC (generados directamente desde el bucle de cierre del RFC)
• Elementos del plan de ruta del proyecto (colocados directamente por el Equipo Central)

4.4 Exploración de la arquitectura

La exploración de arquitectura puede comenzar en Discussions cuando la cuestión está orientada a la comunidad y aún no está lista para un RFC formal. Esto reduce la barrera para plantear inquietudes de diseño sin convertir cada idea temprana en una política rastreada.

Cuando el hilo llegue a una propuesta de arquitectura concreta, abre el issue de RFC y mueve la propuesta duradera a la superficie de RFC. La Discussion puede entonces enlazar al RFC y dejar de ser la fuente de verdad.

4.5 Gestión de Discusiones y Transferencia de Discord a GitHub

Discord es para conversaciones rápidas. GitHub es el registro duradero. Discussions es una superficie de GitHub mantenida para conversaciones de cara a la comunidad que necesitan más permanencia que Discord pero que aún no son trabajo en seguimiento.

Las Discussions están activas solo cuando alguien es responsable del canal. Esa responsabilidad puede recaer en un encargado designado o en una cadencia de revisión documentada. Sin un responsable, las Discussions son un archivo pasivo, no una vía de entrada obligatoria.

Usa Discussions para hilos exploratorios, orientados a la comunidad o de retroalimentación amplia. Usa un issue, un issue de RFC, un comentario de PR o documentación del maintainer cuando el resultado ya sea concreto o autoritativo. La lista de desencadenantes orientada a colaboradores y los ejemplos de categorías se encuentran en Communication.

El traspaso no necesita copiar todo el chat. Captura el resultado y suficiente contexto para que otro mantenedor pueda continuar. Si más adelante una discusión produce trabajo rastreado o una política duradera, promueve ese resultado a la superficie que lo posee.

5. Niveles de equipo y autoridad de contribución

5.1 Las tres capas

Los proyectos de código abierto funcionan según la meritocracia: la influencia y la autoridad provienen de la contribución demostrada, no de la antigüedad, el título o los contactos que se tengan. Esta es una de las cosas que diferencia al código abierto del software corporativo, y vale la pena enseñarlo de manera explícita.

Los tres niveles reflejan un compromiso demostrado cada vez mayor con el proyecto:

Nivel 1: Comunidad

Cualquiera. No se requiere aprobación.

Qué pueden hacer:

• Abre problemas utilizando las plantillas de problemas
• Comenta en cualquier problema o solicitud de extracción (PR)
• Participar en discusiones y votar por ideas
• Enviar solicitudes de extracción (que serán revisadas antes de fusionarse)
• Editar la Wiki de GitHub

Lo que no pueden hacer:

• Asignar problemas (puede solicitar que se le asignen)
• Aprobar PRs
• Fusionar solicitudes de extracción (PRs)
• Votar en las RFCs con autoridad vinculante

Nivel 2: Colaborador

Miembros de la comunidad que han tenido al menos dos PRs fusionados en la rama master.

Cómo convertirse en uno: Tener dos PR fusionados, reconocidos por un miembro del Core Team. El nivel 2 no cuenta con un registro de membresía permanente en la actualidad; consulte §5.3.

Qué obtienen más allá de la Comunidad:

• Se pueden asignar problemas
• Se puede solicitar como revisor en las PRs (revisión no obligatoria)
• Votar en Ideas de las Discusiones cuenta para el umbral de promoción
• Puede solicitar discusiones de RFC sin pasar primero por las Discusiones.

Lo que aún no pueden hacer:

• Aprobar PRs para rutas de alto riesgo
• Fusionar solicitudes de extracción (PRs)
• Votar en la solicitud de comentarios (RFC) de vinculación

¿Por qué existe esta categoría?: Establece un primer hito visible y alcanzable para los nuevos colaboradores. La pregunta “¿Cómo puedo involucrarme más?” tiene una respuesta clara: conseguir que se fusionen dos solicitudes de extracción (PR). Esto motiva las primeras contribuciones de calidad y ofrece al equipo una manera de reconocer públicamente a los colaboradores.

Nivel 3: Equipo principal

Colaboradores que han demostrado contribuciones constantes y de alta calidad a lo largo del tiempo y han sido invitados por miembros existentes del Equipo Principal.

Cómo llegar a serlo: Por invitación de los miembros existentes del Core Team, anunciada públicamente en Discussions. No existe un umbral formal; es una decisión basada en la calidad, consistencia y alineación de las contribuciones previas.

¿Qué obtienen más allá de Contributor:

• Acceso de escritura al repositorio
• Puede fusionar solicitudes de extracción (PRs) que hayan cumplido con los requisitos de revisión.
• Puede aprobar PRs para rutas de Alto Riesgo (sujeto a los requisitos de CODEOWNERS)
• Votar en las propuestas de RFC
• Puedes mover elementos a través de la canalización del proyecto
• Pueden cortarse las versiones
• Participar en las decisiones de gobernanza (discusiones del Equipo Central)

Responsabilidades:

• Triar los nuevos problemas dentro de los 3 días hábiles
• Revisa las solicitudes de extracción (PRs) en su área de especialización dentro de los 5 días hábiles.
• Participar en las votaciones de RFC
• Cumple con el Código de Conducta del proyecto

5.2 La regla del consenso perezoso

Para decisiones rutinarias, como añadir una etiqueta, cerrar un issue inactivo o actualizar la documentación, los miembros del Core Team operan bajo consenso tácito: si anuncias tu intención en el issue correspondiente y ningún miembro del Core Team objeta en un plazo de 48 horas, procedes. Esto evita la parálisis de requerir aprobación explícita para todo, manteniendo a la vez la visibilidad.

El consenso perezoso no se aplica a:

• Aceptación o rechazo de RFC
• Lanzamientos
• Cambios en CODEOWNERS o reglas de protección de ramas
• Cambios en este documento de gobernanza
• Adiciones al Equipo Central

Estos siempre requieren votos explícitos del Equipo Central.

5.3 Registro de la membresía del equipo

La membresía en sí se establece por decisión, no por ningún archivo ni configuración de GitHub. Según §5.1, alguien pasa a formar parte del Core Team por invitación de los miembros existentes del Core Team, anunciada públicamente en Discussions. Esa decisión, y su anuncio público, es la fuente de verdad. Todo lo siguiente es un registro de algo derivado de ello, y ninguno de ellos es una lista de miembros:

El equipo de GitHub core-contributors y la lista de colaboradores del repositorio, en la configuración de la organización: controles de acceso, no registros de membresía. Responden a quién puede escribir en el repositorio, lo cual es una consecuencia de la membresía y no una definición de ella. Se espera que difieran de la lista de miembros en ambas direcciones. Incluyen cuentas de automatización que no son personas, y el acceso puede otorgarse directamente, mantenerse desde antes de una decisión de membresía, o estar pendiente de aceptación de una invitación. Cuando necesites saber quién puede hacer push, consulta estos. Cuando necesites saber quién es parte del Core Team, consulta el anuncio que los admitió.

.github/CODEOWNERS en la raíz del repositorio: enrutamiento de revisiones, no membresía. Registra a quién se solicita revisión en qué rutas. Estar en la lista no confiere membresía y ser miembro no implica estar en la lista. Los cambios en él requieren una votación explícita del Equipo Central, según §5.2.

La tabla de mantenedores en Comunicación: el resumen legible de los miembros actuales y de aquello en lo que trabaja cada uno. Es lo más parecido a una lista publicada, y se mantiene manualmente, así que trátala como un resumen de las decisiones de incorporación, no como una fuente de autoridad. En cuanto a las áreas de enfoque, es una vista práctica de CODEOWNERS y, cuando ambas no coinciden, prevalece CODEOWNERS.

Las remociones funcionan igual que las admisiones: son decisiones, registradas donde se toman. Revocar el acceso o eliminar a alguien de CODEOWNERS implementa una salida; no constituye una por sí mismo.

Las revisiones 1 a 7 de este documento especificaban un archivo CONTRIBUTORS.md en la raíz del repositorio como registro de membresía organizado por niveles, y nombraban los equipos de GitHub zeroclaw-core y zeroclaw-contributors. Ninguno de los tres fue creado; la organización utiliza en su lugar un único equipo core-contributors. El RFC #6808 llegó de forma independiente a la misma conclusión, registrando que la estructura de niveles de equipo FND-003 no es el modelo de enrutamiento vigente visible y que las nuevas reglas de carril no deben construirse sobre ella. Dichas referencias se retiran aquí en lugar de dejarse como descripción de una maquinaria que no existe.

El Nivel 2 no tiene actualmente ningún registro de membresía duradero. Establecer uno, o retirar el nivel, es una pregunta abierta para el equipo.

6. CODEOWNERS y Protección de Ramas

6.1 CODEOWNERS

El archivo CODEOWNERS automatiza la gobernanza. Define qué rutas requieren revisión de qué equipo antes de que un PR pueda fusionarse. GitHub lo aplica como una revisión obligatoria: el PR no puede fusionarse hasta que se cumpla el requisito.

El bloque que aparece a continuación es la propuesta ilustrativa original, conservada por el razonamiento que muestra sobre el enrutamiento de revisiones protegidas. No es el archivo actual y no debe copiarse. .github/CODEOWNERS ya existe y se mantiene activamente; enruta a identificadores individuales en lugar de identificadores de equipo, y sus rutas siguen el diseño de crates posterior a microkernel establecido en #6537. Los identificadores @zeroclaw-labs/zeroclaw-core y @zeroclaw-labs/zeroclaw-contributors usados aquí nunca se crearon; consulta §5.3. Sus rutas de enrutamiento amplias no corresponden al clasificador actual risk:high; consulta el archivo activo y la guía de etiquetas de mantenedores para conocer el enrutamiento actual y la semántica del riesgo.

# CODEOWNERS — Automatic review routing by protected surface
# See the maintainer label guide for risk definitions.
# See the governance foundation doc and RFC issue template for team tier definitions.

# ── Protected review routing: Core Team review ──────────────────────────────

src/security/**                 @zeroclaw-labs/zeroclaw-core
src/gateway/**                  @zeroclaw-labs/zeroclaw-core
src/runtime/**                  @zeroclaw-labs/zeroclaw-core
src/tools/shell.rs              @zeroclaw-labs/zeroclaw-core
src/tools/file_write.rs         @zeroclaw-labs/zeroclaw-core
src/tools/security_ops.rs       @zeroclaw-labs/zeroclaw-core

# ── Governance and configuration: requires Core Team approval ───────────────

.github/**                      @zeroclaw-labs/zeroclaw-core
CODEOWNERS                      @zeroclaw-labs/zeroclaw-core
Cargo.toml                      @zeroclaw-labs/zeroclaw-core
deny.toml                       @zeroclaw-labs/zeroclaw-core

# ── Architecture documents: requires Core Team review ───────────────────────

docs/book/src/foundations/**    @zeroclaw-labs/zeroclaw-core
docs/book/src/architecture/decisions/**  @zeroclaw-labs/zeroclaw-core
AGENTS.md                       @zeroclaw-labs/zeroclaw-core

# ── Default: any Contributor or Core Team member can review ─────────────────

*                               @zeroclaw-labs/zeroclaw-contributors

A medida que miembros específicos del Core Team asuman la responsabilidad de componentes, agregue sus identificadores individuales junto al identificador del equipo. La especificidad gana en CODEOWNERS: una regla de ruta más específica anula una más general.

6.2 Reglas de protección de ramas

Configura las siguientes reglas de protección de ramas para master:

Por qué los administradores no pueden omitir las reglas: Uno de los errores más comunes en proyectos de equipos pequeños es tratar la protección de ramas como algo “para los demás”. Cuando un administrador puede omitir las reglas, lo hará: bajo presión de tiempo, en una emergencia, “solo por esta vez”. Y luego se convierte en la norma. La regla debe aplicarse a todos para que tenga sentido. Si hay una emergencia genuina, la respuesta correcta es seguir el proceso más rápido, no saltárselo.

El recuento de aprobaciones nativo de GitHub se configura por rama protegida o destino del conjunto de reglas, no de forma condicional según la etiqueta de la PR. Hasta que un diseño técnico de aplicación aprobado por separado disponga de una autoridad legible por máquina para la aprobación del Core Team, los mantenedores deben aplicar el requisito risk:high OR domain:security mediante la lista de comprobación de merge documentada y conservar un registro de revisión auditable. risk:manual solo congela la sustitución automática futura del riesgo; no puede reducir este requisito.

6.3 Verificaciones de estado requeridas

Las comprobaciones de CI que deben pasar antes de que cualquier PR pueda fusionarse:

build (stable)          ← cargo build --release
test                    ← cargo test
fmt                     ← cargo fmt --all -- --check
clippy                  ← cargo clippy --all-targets -- -D warnings

A medida que el espacio de trabajo se descompone en crates (según el RFC de arquitectura), añade comprobaciones por crate. Un cambio en crates/zeroclaw-api debería ejecutar el conjunto de pruebas de ese crate de forma independiente.

6.4 Cumplimiento Arquitectónico: Revisión Humana, Soporte de IA

Esta sección existe porque la pregunta surgirá (ya ha surgido) y merece una respuesta clara y documentada en lugar de un debate en cada PR.

La pregunta: ¿Deberíamos agregar un control automático que verifique si un PR se ajusta a la arquitectura y los patrones de diseño definidos en las RFC?

La respuesta: No. Y entender por qué es importante.

Existen dos tipos fundamentalmente diferentes de aplicación de la calidad, y requieren mecanismos distintos.

El primer tipo es la cumplimiento estructural: ¿este código viola una regla mecánica? ¿zeroclaw-kernel importa TelegramChannel? ¿Los bordes del grafo de dependencias apuntan en la dirección incorrecta? ¿Hay advertencias de clippy? Estas son preguntas binarias. O el código viola la regla o no. El compilador, cargo deny y cargo clippy --workspace ya imponen esto. No se necesita un humano. No se necesita una IA. La máquina es autoritativa, rápida y nunca se equivoca sobre una violación factual.

El segundo tipo es la intención arquitectónica: ¿esta decisión pertenece aquí? ¿Esta abstracción está en la capa correcta? ¿Este compromiso se alinea con la visión? ¿Este acoplamiento va a ser doloroso en la Fase 3? ¿Este PR creará una carga de mantenimiento que no es visible en el diff hoy? Estas preguntas requieren criterio, contexto y una comprensión de por qué existe la arquitectura, no solo de cuáles son las reglas. Ninguna herramienta automatizada puede responderlas de manera confiable, porque la respuesta depende de información que no está en el diff: la hoja de ruta, las prioridades actuales del equipo, la intención del colaborador y el costo a largo plazo de la decisión.

Los modos de fallo de la automatización del juicio arquitectónico son ambos malos.

Una compuerta que deja pasar violaciones arquitectónicas sutiles crea falsa confianza. El desarrollador ve ✅ y asume que su decisión fue validada. La deriva arquitectónica más dañina, del tipo que toma años desenredar, parece estructuralmente correcta. Compila. Pasa el lint. El grafo de dependencias está bien. El problema es que violó el espíritu del diseño de una manera que solo se hace evidente más tarde, cuando el costo de revertirla es alto.

Un gate que marca como válidas las decisiones arquitecturales porque la herramienta interpretó mal el contexto enseña a los desarrolladores a ignorar completamente el gate. Una vez que un equipo aprende a hacer clic para pasar por alto una verificación automatizada ruidosa, la verificación desaparece en la práctica, aunque siga ejecutándose en CI. El proyecto ha gastado minutos de CI para obtener un valor negativo.

CODEOWNERS es el filtro de cumplimiento arquitectónico. El revisor es la herramienta.

La configuración de CODEOWNERS en §6.1 ya dirige superficies de revisión protegidas, como los límites de los crates, las definiciones de traits, el grafo de dependencias, src/security/ y .github/, a un revisor del Core Team. Este enrutamiento es distinto de la clasificación risk:*. El revisor del Core Team, con los RFCs como marco de referencia, es el control de cumplimiento arquitectónico. Aporta el criterio contextual que ninguna automatización puede replicar.

Por eso existen los RFC, los archivos AGENTS.md y las normas de documentación: no para que una máquina los analice y genere una puntuación, sino para que un revisor humano tenga un marco coherente y documentado en el que basarse. El RFC responde a “¿por qué existe esta arquitectura?”. El revisor responde a “¿este PR contribuye o socava ese propósito?”.

La IA pertenece al ciclo de desarrollo, no al control de fusión.

Las herramientas de IA, Claude, Copilot, Cursor, y lo que venga después, son genuinamente útiles para el trabajo de arquitectura cuando se usan en el lugar correcto. El lugar correcto es durante el desarrollo, no durante la validación previa al merge.

Durante el desarrollo, un asistente de IA equipado con el RFC y el archivo AGENTS.md del crate puede ayudar a un colaborador a comprender en qué crate debe ir una nueva funcionalidad antes de escribirla, señalar una posible inversión de dependencias mientras el código aún se está definiendo, explicar por qué existe un patrón de diseño y sugerir si una nueva abstracción está en la capa adecuada. Esto es aditivo. Hace que los colaboradores sean más capaces.

Durante una revisión, un asistente de IA puede ayudar a un revisor humano a redactar comentarios estructurados, comparar un cambio con la RFC e identificar cuáles de las preguntas de discusión en la RFC son relevantes para la PR. Esto también es aditivo. El revisor aporta el juicio; la IA aporta velocidad y capacidad de recuperación.

Lo que la IA no puede hacer es reemplazar el juicio. “La IA me ayuda a evaluar este PR” y “la IA aprueba automáticamente este PR” son categóricamente diferentes, y solo lo primero funciona para decisiones arquitectónicas. El día en que el proyecto haga pasar el cumplimiento arquitectónico por una validación automatizada, por sofisticada que sea, es el día en que la arquitectura empieza a desviarse de maneras que nadie nota hasta que es demasiado tarde.

La política práctica, expresada de manera clara:

• La conformidad estructural (dirección de importación, grafo de dependencias, lint, formato) se aplica mediante CI. Esto es innegociable y automatizado.
• El cumplimiento de la intención arquitectónica se garantiza mediante el enrutamiento de CODEOWNERS a un revisor del equipo principal. Esto es innegociable y requiere intervención humana.
• Las herramientas de IA apoyan a los colaboradores durante el desarrollo y a los revisores durante la revisión. No bloquean las fusiones por su propia autoridad.
• Si el equipo desea evaluar herramientas de revisión asistidas por IA en el futuro, esa evaluación debe pasar primero por el proceso de RFC. No se añadirá a .github/workflows/ sin una decisión documentada.

Esta política no es una limitación para la IA ni para la automatización. Es un reconocimiento de que diferentes problemas requieren diferentes herramientas, y usar la herramienta adecuada en el lugar correcto es exactamente lo que la RFC de arquitectura está solicitando al código base.

7. Plantillas de emisión

Las plantillas de incidencias dirigen los informes entrantes al proceso adecuado antes de que lleguen a un humano. Una plantilla bien redactada recopila automáticamente la información necesaria para la triaje. Una plantilla faltante o ignorada da lugar a incidencias que requieren tres intercambios de comentarios para entenderlas.

La fuente de verdad operativa es .github/ISSUE_TEMPLATE/. No dupliques aquí el YAML completo de la plantilla. Cuando cambie la redacción de la plantilla, actualiza el propio formulario de incidencias y mantén esta sección a nivel de intención duradera.

Carriles de admisión actuales:

Las vulnerabilidades de seguridad no tienen una plantilla de issue pública. config.yml enlaza a la política de seguridad privada, Discord, GitHub Discussions, la guía de contribución, el proceso de RFC y el flujo de trabajo de PR de mantenedores para que los colaboradores puedan elegir la superficie adecuada antes de crear un issue rastreable.

Las plantillas de issues recopilan evidencia; no deciden las etiquetas finales por sí mismas. Los maintainers siguen aplicando etiquetas basadas únicamente en criterio, como status:accepted, status:no-stale, help wanted y good first issue, después de revisar el cuerpo, la discusión y el trabajo vinculado. En particular, status:no-stale no debe aplicarse automáticamente desde una plantilla. Un tracker, un RFC o un issue aceptado de larga duración debe registrar tanto el motivo de exención de obsolescencia como la siguiente decisión visible o el punto de revisión antes de que se añada o se mantenga la protección contra obsolescencia.

8. El ciclo de gobernanza de RFC

El proceso de RFC se estableció en el RFC de documentación y el RFC de arquitectura. Esta sección define el ciclo de cierre: cómo un RFC pasa de propuesta a decisión y a acción.

Cuándo es necesario un RFC. Un RFC registra una decisión duradera a nivel de proyecto antes de la implementación. Se requiere uno cuando la propuesta cumple al menos una de las siguientes condiciones:

• una nueva capa de seguridad o un cambio sustancial en el modelo de seguridad del proyecto;
• un cambio de gobernanza, del proceso de contribución o de la autoridad del proyecto;
• una refactorización arquitectónica transversal que cambia la propiedad o los contratos entre límites establecidos; o
• un nuevo subsistema u otro límite de capacidades de todo el proyecto.

No exijas un RFC únicamente porque el trabajo incluya una adición de funcionalidad ordinaria, una migración de esquema o de datos, un cambio en un campo de configuración o en su valor predeterminado, o una refactorización acotada de la implementación. Estos casos se gestionan mediante una incidencia y un PR. Solo requieren un RFC cuando su efecto sustantivo también cumpla una de las condiciones anteriores.

El criterio de activación se basa en el efecto sustantivo en el proyecto, no en el título de la incidencia, el autor, un origen asistido por IA ni la mera presencia de una migración, una funcionalidad o un cambio en el valor predeterminado. Las vulnerabilidades de seguridad se notifican de forma privada, nunca mediante una RFC pública.

Los mantenedores pueden cambiar la etiqueta de un RFC presentado o cerrarlo como una incidencia ordinaria, una solicitud de funcionalidad o un seguimiento de implementación cuando no cumpla el criterio de activación. La resolución indica si el trabajo subyacente sigue siendo válido y dónde continúa. Esto sirve para encauzar el trabajo; no constituye un rechazo de fondo.

8.1 El ciclo de vida completo del RFC

Las revisiones y aclaraciones ordinarias del autor durante el debate no reinician el plazo. Una revisión que cambie sustancialmente la decisión propuesta establece una nueva instantánea estable, identificada públicamente, y reinicia el periodo mínimo de debate aplicable.

1. AUTHOR opens an RFC issue using the RFC issue template,
   naming the trigger the proposal crosses
           |
2. DISCUSSION PERIOD, against a visible proposal
     minimum 48 hours for an ordinary RFC
     minimum 72 hours when the exceptional unanimous path is requested
   Anyone can comment. Core Team members engage substantively.
           |
3. VOTE OPENS once the period has elapsed and the proposal is stable.
   The vote-opening comment records:
     - the immutable proposal snapshot (artifact, commit, or issue-body digest)
     - the assigned active electorate, and inactive Core notified for re-entry
     - the threshold, and why it applies
     - that quorum requires two explicit ballots
     - the exact UTC deadline, 72 hours after opening
           |
4. CORE TEAM BALLOTS, one of:
     APPROVE  accept the snapshot as written
     REVISE   request changes, withhold approval, do not veto
     REJECT   blocking objection, with a specific reason
   A member's latest ballot before the deadline supersedes their earlier one.
           |
5. OUTCOME, applied in this precedence order:
     a. Fewer than two explicit ballots        -> DEFERRED
     b. Quorum met and any final ballot REJECT -> REJECTED
     c. Quorum met, no REJECT, two-thirds
        approving explicitly or by silence     -> ACCEPTED
     d. Otherwise                              -> RETURNED TO DISCUSSION

Los RFC aceptados llevan status:accepted, y el registro de cierre aborda todas las inquietudes de REVISE en lugar de descartarlas. Los RFC rechazados se cierran con la objeción bloqueante registrada y un enlace a cualquier incidencia en la que continúe el problema subyacente; el rechazo pone fin a la propuesta actual, pero no necesariamente al problema. Las propuestas aplazadas permanecen abiertas con la condición para otra votación registrada, y una propuesta aplazada sin cambios puede volver a someterse a una nueva votación de 72 horas sin repetir el debate.

Usa las etiquetas vigentes type:rfc y status:accepted. No existe una familia paralela de etiquetas de estado rfc:*.

La revisión 15 se aplica a las votaciones de RFC abiertas después de la ratificación. No invalida automáticamente los RFC aceptados anteriormente; el trabajo de auditoría y corrección del proceso histórico se sigue registrando por separado.

Una votación solo podrá cerrarse antes de tiempo cuando todos los miembros del electorado activo final hayan dado su aprobación explícita y ningún colaborador de Core que, de otro modo, estaría inactivo haya solicitado el plazo completo. El registro de cierre debe indicar por qué se cerró antes de la fecha límite. Una votación unánime excepcional solo podrá cerrarse antes de tiempo si todos los votantes asignados han dado su aprobación explícita.

8.2 Umbrales de votación

Dos tercios del electorado activo final constituyen el umbral predeterminado, redondeado al alza a un número entero de votantes. El electorado activo final es el electorado asignado al inicio más cualquier otro miembro actual del Core Team que emita su voto en esa misma votación.

• Quorum requiere que al menos dos colaboradores actuales de Core emitan un voto explícito. El silencio nunca cuenta para alcanzar el quórum.
• El silencio cuenta como APPROVE por parte del electorado activo final una vez alcanzado el cuórum, únicamente para votaciones ordinarias.
• REVISE cuenta como una no aprobación y no tiene poder de veto.
• REJECT veta la aceptación una vez que se alcanza el quórum.

Por ejemplo, con cuatro miembros en el electorado activo final, un APPROVE explícito, un REVISE explícito y dos miembros silenciosos producen tres aprobaciones de cuatro, lo que cumple el umbral.

La unanimidad se reserva para decisiones cuyo coste o irreversibilidad hacen insuficiente la aprobación por supermayoría, como los cambios en la licencia o en la titularidad legal. La apertura de la votación debe explicar por qué se aplica la unanimidad. Una votación unánime requiere un APPROVE explícito de cada colaborador de Core asignado que sea elegible; el silencio no puede establecer la unanimidad.

Electorado activo. Un colaborador actual del Core es un miembro actual del Core Team que emitió una papeleta explícita de APPROVE, REVISE o REJECT en una votación de RFC abierta formalmente durante los 30 días anteriores y que no se haya apartado públicamente ni haya dejado constancia de su indisponibilidad durante el periodo de votación. Se notifica a los miembros actuales inactivos del Core y pueden incorporarse al electorado final de una votación al emitir su voto en ella, lo que también los reactiva para votaciones posteriores.

El quórum y el denominador se determinan por separado para cada votación. La actividad se comprueba cuando se abre la votación; la actividad posterior en otra votación simultánea no cambia el electorado de una votación ya abierta.

8.2a Decisiones fundamentales de la reunión y GitHub Bridge

GitHub es la fuente de verdad para el texto de la propuesta, los debates, las aperturas de votación, las papeletas, los plazos y los resultados. Discord puede anunciar o debatir un RFC, pero no establece el estado de la gobernanza.

Las decisiones de las reuniones de colaboradores principales registradas en el registro interno de decisiones aprobado del proyecto pueden guiar las acciones inmediatas de los mantenedores y prevalecer sobre directrices internas anteriores. Cualquier acción de este tipo que cambie el estado público del proyecto debe dejar un registro puente en GitHub en la incidencia, PR, rastreador o RFC afectado. El registro puente indica la fecha de la reunión o el registro de decisiones, resume la decisión aplicada, especifica la acción pública realizada y señala si se trata de una excepción puntual o de un cambio permanente de las reglas.

Las decisiones de las reuniones no modifican silenciosamente este documento, la documentación para colaboradores, las etiquetas, las plantillas de incidencias ni los resultados de las RFC. Los cambios duraderos en la gobernanza solo se convierten en política cuando se reflejan en los recursos pertinentes de GitHub y de la documentación. En el caso excepcional de decisiones unánimes, un acta interna de la reunión no puede sustituir las aprobaciones explícitas requeridas en GitHub, a menos que dicha acta documente qué miembros dieron su aprobación y la incidencia pública deje constancia de ese fundamento.

8.3 Seguimiento duradero y la conexión con ADR

Para los RFC aceptados recientemente, la forma definitiva y el seguimiento sostenido deben ser visibles en la incidencia del RFC antes de proceder con la implementación. La aceptación por sí sola no completa la transferencia de gobernanza. En el caso de los RFC aceptados que se auditen después de la implementación, registra retrospectivamente la resolución sin reabrir el trabajo completado.

Cada registro de disposición identifica la forma final canónica, la disposición seleccionada y su justificación, el artefacto duradero o el seguimiento de entrega, y el responsable o la siguiente acción cuando aún queda seguimiento.

Usa una de las cuatro disposiciones:

• ADR: obligatorio cuando la decisión restringe materialmente la arquitectura futura. Entre los indicadores se incluyen una frontera del sistema inesperada, un compromiso no evidente o una elección que limita materialmente las alternativas de arquitectura futura.
• Actualización de documento permanente: requerida cuando el resultado duradero es un documento operativo, de referencia, de flujo de trabajo, de seguridad o un contrato de usuario, en lugar de una nueva decisión de arquitectura.
• Seguimiento de implementación o rastreo: requerido cuando un ADR, FND o documento vigente existente ya contiene la decisión y queda trabajo de entrega pendiente. Vincule el rastreador de entrega y su próxima acción.
• Sin artefacto independiente: permitido cuando un FND, ADR, documento vigente, implementación completada o decisión posterior identificados ya conservan el resultado y no queda ningún seguimiento adicional de la entrega. La incidencia debe registrar esa justificación y enlazar a la referencia permanente.

Un RFC es el ámbito de discusión y aceptación. Un ADR es el registro permanente de una decisión de arquitectura significativa, no un resumen obligatorio de cada RFC aceptado. Los documentos vigentes y los rastreadores de implementación no sustituyen a un ADR cuando la decisión aceptada cumple el umbral de arquitectura indicado arriba.

8.4 RFC fundamentales

Los documentos de propuesta inicial desde entonces se han representado como issues de RFC y documentos de la fundación:

9. Taxonomía de etiquetas

Las etiquetas son la capa de metadatos en los issues y PRs. Un sistema de etiquetas consistente y bien diseñado hace posible el filtrado, la generación de informes y la automatización. Un sistema de etiquetas inconsistente (el caso común, etiquetas añadidas de forma improvisada por quien crea el issue) genera ruido.

Utiliza un sistema de etiquetas con espacio de nombres. Cada etiqueta tiene un prefijo que identifica su categoría:

type: ¿Qué tipo de trabajo es este?

priority: ¿Qué tan urgente es esto?

size: ¿Qué tan grande es este elemento de trabajo?

component: ¿Qué parte del sistema?

component:kernel · component:gateway · component:channels · component:tools · component:memory · component:security · component:hardware · component:docs · component:infra

Utiliza #f1f5f9 (gris claro) para todas las etiquetas de componentes para distinguirlas visualmente de otras categorías.

risk: ¿Cuál es el nivel de riesgo? (refleja AGENTS.md)

status: ¿En qué punto del proceso se encuentra?

Esta tabla registra la intención de gobernanza y la estructura histórica de la taxonomía. Para la semántica actual de las etiquetas en producción y el comportamiento de automatización, utiliza la guía de etiquetas para mantenedores como referencia operativa; la documentación para mantenedores incluye correcciones posteriores a la política de etiquetas del #6808.

Las etiquetas activas para que la comunidad tome tareas son good first issue y help wanted sin prefijo; las filas de tareas status:* de arriba son taxonomía histórica. Las etiquetas operativas actuales de riesgo también distinguen el riesgo de la incidencia (radio de impacto probable de la corrección según el reporte) del riesgo del PR (el diff real en revisión). Consulta la guía de etiquetas para mantenedores para conocer la política activa.

Las etiquetas de cierre terminal son política operativa, no forman parte de la taxonomía histórica status:* de este documento fundacional. Usa la guía de etiquetas para mantenedores para las etiquetas de resolución actuales y la guía de sustitución para las reglas del proceso de reemplazo.

rfc: Estado específico del RFC

Retiradas en la Rev. 15 y nunca creadas como etiquetas activas. El estado de RFC usa las etiquetas activas type:rfc y status:accepted; consulta §8.1.

10. Definición de Terminado

“Hecho” significa algo específico. Si no lo defines, cada persona tendrá una definición diferente, y los desacuerdos saldrán a la luz en el peor momento posible: durante la revisión, durante el lanzamiento, o después de que un usuario reporte un error.

Un elemento está Completado cuando se cumplen todas las siguientes condiciones:

Para cambios de código

• La PR ha sido revisada y aprobada por el nivel de revisores requerido (según CODEOWNERS y nivel de riesgo).
• Todas las comprobaciones de CI se han ejecutado correctamente: cargo fmt, cargo clippy, cargo test
• Existen pruebas para el nuevo o cambiado comportamiento (pruebas unitarias como mínimo; pruebas de integración para características visibles para el usuario)
• No se perdió la cobertura de pruebas que estaba pasando antes del PR
• La descripción del PR explica qué cambió y por qué (no solo “se corrigió un error”: qué error, qué estaba mal, qué se cambió)
• Si el cambio afecta el comportamiento visible para el usuario, la documentación de referencia correspondiente se actualiza en el mismo PR.
• Si el cambio es significativo: se agrega una entrada en el archivo CHANGELOG.md bajo la sección correspondiente del hito.
• Si el cambio requiere un ADR: el ADR se escribe, enlaza y fusiona antes o junto con el PR de implementación.

Para cambios en la documentación

• El frontmatter YAML está presente y es válido
• Todos los enlaces internos se resuelven correctamente
• Si el documento describe un comportamiento actual: es preciso en relación con la rama master actual.
• Si el documento es un ADR: sigue el formato de Nygard y tiene un campo status.

Para versiones

• Todos los elementos del hito están en estado Done o se han movido explícitamente al siguiente hito con un comentario que explica por qué.
• La entrada del CHANGELOG.md para la versión está completa.
• Cada RFC aceptada en este hito tiene registrada una resolución duradera; las ADR requeridas y las actualizaciones de los documentos permanentes están fusionadas, y los rastreadores de entrega restantes están vinculados
• La versión ha sido probada en al menos una plataforma (Linux x86_64 como mínimo).
• La etiqueta de la versión sigue el Versionado Semántico

La regla “Hecho Hecho”

En los equipos de desarrollo de software existe el concepto de trabajo que está “hecho” pero no “hecho del todo”. “Hecho” significa que el código ha sido escrito. “Hecho del todo” implica que ha sido probado, documentado, revisado, fusionado y liberado. La Definición de Hecho descrita anteriormente se refiere a “hecho del todo”. Nada debe considerarse como terminado hasta que cumpla con la definición completa.

11. Automatización

GitHub Projects v2 y GitHub Actions, en conjunto, permiten una automatización significativa que reduce la sobrecarga de la coordinación manual. A continuación se detalla lo que se debe implementar, ordenado por la relación valor-esfuerzo.

11.1 Automatización del tablero del proyecto (integrada, no requiere acciones)

Configura estos ajustes en la automatización integrada del proyecto:

11.2 Flujos de trabajo de GitHub Actions

Etiquetado automático según los archivos modificados:

El etiquetador de rutas activo aplica etiquetas de alcance a los PR según los archivos modificados. Las etiquetas de riesgo y tamaño actualmente las aplican los mantenedores; la guía de etiquetas para mantenedores es la fuente activa para los nombres de etiquetas, el estado de automatización y la semántica de riesgo.

Solicitar automáticamente la revisión de CODEOWNERS (integrado en CODEOWNERS: no se necesita ninguna Action):

GitHub aplica automáticamente CODEOWNERS cuando el archivo existe y la protección de rama lo requiere. No se requiere ninguna acción.

Gestión de incidencias obsoletas (ejecutada por mantenedores):

No hay ningún flujo de trabajo de GitHub Actions para issues obsoletos configurado actualmente en el repositorio. Los mantenedores ejecutan pasadas de obsolescencia para evitar que los issues inactivos se acumulen, preservando al mismo tiempo una ventana de respuesta definida para la comunidad afectada. La política de issues obsoletos es la única fuente operativa para los tiempos, la actividad que califica, las exclusiones y la reactivación; el protocolo de clasificación de issues solo contiene la mecánica de ejecución.

Etiquetado del tamaño del PR (futuro/opcional):

Si la automatización de tamaños se añade más adelante, debe seguir los nombres vigentes de la guía de etiquetas del mantenedor (size:XS through size:XL) y recalcularse en las actualizaciones enviadas para que la etiqueta describa el diff en revisión. Hasta entonces, las etiquetas de tamaño las aplica el mantenedor.

Verificación de hito al fusionar PR (.github/workflows/milestone-check.yml):

Advertir (no bloquear) si un PR se fusiona sin un issue vinculado que tenga un milestone asignado. Es un recordatorio suave, no una restricción estricta: el objetivo es evitar que el trabajo se realice sin estar asociado al seguimiento de una versión.

11.3 Qué NO automatizar aún

• Borradores de lanzamiento automatizados: El release-drafter de GitHub es útil, pero añade una sobrecarga de configuración. Añádelo después de que el equipo haya establecido un ritmo de lanzamiento estable.
• Actualizaciones automáticas de dependencias (PRs de Dependabot): Habilita las actualizaciones de seguridad de Dependabot (gratuitas y con bajo nivel de ruido), pero pospone los cambios automáticos de versión hasta que el equipo tenga estabilidad en CI. Los cambios de versión generan ruido antes de que la base de CI esté consolidada.
• Automatización de la planificación de sprints: No automatice la planificación de sprints. Requiere juicio humano sobre la capacidad, la prioridad y el contexto del equipo, algo que ninguna automatización puede reemplazar en este tamaño de equipo.

12. Implementación por fases

La gobernanza y las herramientas deben introducirse de forma incremental. Introducir todo de una vez genera sobrecarga antes de que el equipo entienda por qué existe cada pieza.

Fase 1 · Esta semana: “Fundamentos”

La configuración mínima viable de gobernanza. Permite que el equipo comience a coordinarse de inmediato.

• Crea el proyecto de GitHub con los campos Estado, Tipo, Prioridad y Hito.
• Crea las cuatro vistas del proyecto (Hoja de ruta, Tablero, Backlog, Mi trabajo)
• Habilita GitHub Discussions con categorías mantenidas documentadas en la documentación de comunicación de colaboradores y flujo de trabajo de mantenedores
• Crea los tres problemas RFC para las propuestas existentes (Sección 8.4)
• Agregue las plantillas de issue enumeradas en la Sección 7
• Crea el archivo CODEOWNERS (Sección 6.1)
• Habilitar las reglas de protección de ramas en master (Sección 6.2)
• Agregue la taxonomía de etiquetas restante (Sección 9) al repositorio
• Fija las tres incidencias de RFC y la incidencia del próximo hito de la versión

Señal de éxito: Los nuevos problemas aparecen automáticamente en el Proyecto. El equipo sabe dónde buscar el trabajo activo y dónde publicar las ideas.

Fase 2 · Hito v0.7.0: “The Pipeline”

Establece el flujo de trabajo completo y completa el backlog con los RFCs aceptados.

• Agregue los campos Tamaño, Nivel de Riesgo y Componente al Proyecto
• Rellenar el Backlog con los entregables del RFC de la arquitectura del microkernel
• Rellenar el Backlog con entregables del RFC de estándares de documentación
• Realizar las primeras votaciones formales de las RFC sobre las tres propuestas existentes
• Completar el conjunto de ADR fundacionales seleccionado (ADR-001 a ADR-007 según el RFC de documentación)
• Implementa el flujo de trabajo de Actions para la autoetiquetación por ruta
• Implementa el flujo de trabajo de gestión de problemas obsoletos
• Crea el equipo de GitHub del Core Team, entregado como un único equipo core-contributors en lugar de los dos planeados originalmente. El elemento del listado CONTRIBUTORS.md que lo acompañaba queda retirado; consulta §5.3.

Señal de éxito: El equipo está utilizando el tablero diariamente. Los elementos avanzan por las etapas con verificaciones de puertas visibles. El RFC para la arquitectura del microkernel tiene un resultado de votación registrado.

Fase 3 · Hito v0.8.0: “Haciendo crecer la comunidad”

A medida que el sistema de complementos se vuelva utilizable, los colaboradores externos comenzarán a llegar. La infraestructura de contribución debe estar lista.

• Implementa el flujo de trabajo de etiquetado del tamaño de PR
• Crea el primer lote de elementos good first issue (mínimo 5) para el trabajo del SDK del plugin
• Agregar el Good First Issue Index como una incidencia fijada con enlaces a las incidencias good first issue actuales
• Establece el umbral de promoción de ideas y promueve la primera idea de discusión a un problema
• Documentar el proceso de expansión del Core Team: criterios para invitar a nuevos miembros del Core Team

Señal de éxito: Al menos un colaborador externo (que no pertenezca al equipo actual) envía un PR a través de un good first issue. La categoría Discussions Ideas tiene participación activa de la comunidad.

Fase 4 · v1.0.0: “Gobernanza Sostenible”

Para la versión v1.0.0, el modelo de gobernanza debería ser autosostenible: el equipo no debería tener que pensar en él, simplemente debería funcionar.

• Revisa y actualiza el documento de gobernanza en función de lo que ha funcionado y lo que no.
• Establece la cadencia de las versiones (con qué frecuencia se crean las versiones, quién las crea).
• Publica el documento de gobernanza del registro de complementos (según el RFC de arquitectura)
• Considera introducir ciclos de tiempo acotado (de dos o cuatro semanas) si la planificación solo por hitos parece demasiado flexible.
• Documente el proceso para que un miembro del Equipo Principal renuncie o se vuelva inactivo.

Señal de éxito: Las últimas seis meses del historial de desarrollo muestran un uso constante del pipeline. Los problemas se trian en un plazo de 3 días. Las PRs se revisan en un plazo de 5 días. El CHANGELOG se actualiza en cada fusión.

Apéndice A: Glosario

Backlog grooming: Una actividad regular del equipo (típicamente semanal o quincenal) en la que el equipo revisa el backlog, reprioriza los elementos, cierra los obsoletos y se asegura de que los elementos principales estén “Definidos” y listos para ser tomados.

Protección de ramas: Una característica de GitHub que evita los pushes directos a ramas protegidas y exige requisitos (revisiones, verificaciones de CI) antes de fusionar.

CODEOWNERS: Un archivo de GitHub que solicita automáticamente revisiones de personas o equipos específicos cuando los archivos que les pertenecen se modifican en un PR.

Definición de Terminado: Una lista de verificación compartida que especifica exactamente qué significa “terminado” para un elemento de trabajo. Sin una definición compartida, “terminado” significa algo diferente para cada persona.

Consenso tácito (lazy consensus): Un enfoque de toma de decisiones en el que una acción propuesta procede a menos que alguien presente objeciones dentro de un período de tiempo definido. Reduce la sobrecarga de requerir aprobación explícita para decisiones rutinarias.

Meritocracia: Un modelo de gobernanza en el que la autoridad y la influencia se ganan mediante la contribución demostrada, no por antigüedad o cargo. Es el estándar en proyectos de código abierto.

Milestone: Una funcionalidad de GitHub que agrupa issues y PRs por objetivo de lanzamiento. Un milestone representa una versión del software.

T-shirt sizing: Una técnica de estimación que utiliza tallas abstractas (XS, S, M, L, XL) en lugar de puntos de historia numéricos. Es más fácil de usar sin datos históricos de calibración y suficiente para equipos en una etapa temprana.

Triaje: El proceso de revisar issues nuevos para confirmar que son válidos, asignar etiquetas y prioridad, vincularlos a hitos y determinar si pertenecen al backlog o deben cerrarse.

Apéndice B: Lecturas adicionales

• Documentación de GitHub Projects: Referencia completa de las características de GitHub Projects v2.
• Documentación de GitHub Discussions: Guía de configuración y opciones de gobernanza para GitHub Discussions.
• Referencia de sintaxis de CODEOWNERS: La sintaxis completa para los archivos CODEOWNERS.
• “Producing Open Source Software”: Karl Fogel: El libro definitivo sobre cómo gestionar un proyecto de código abierto. Disponible gratis en línea en producingoss.com. Los capítulos sobre gobernanza, gestión de colaboradores y comunicación son directamente aplicables.
• “An Introduction to Open Source Governance Models”: La documentación de gobernanza de la Apache Software Foundation es un buen modelo de cómo un proyecto de código abierto maduro formaliza la autoridad y la toma de decisiones: https://www.apache.org/foundation/governance/
• Linter de prosa Vale: Vale: Referenciado en el RFC de documentación; se integra con el flujo de trabajo de mejora de documentación de good first issue.

Esta propuesta fue desarrollada en el contexto de ZeroClaw v0.6.8 y los dos RFCs anteriores de arquitectura y documentación. El modelo de gobernanza propuesto aquí es intencionalmente ligero para un proyecto liderado por estudiantes en una etapa temprana de crecimiento de la comunidad. Está diseñado para escalar: agregando procesos a medida que el equipo crece, no todos a la vez.

El mejor modelo de gobernanza es el más simple que el equipo realmente seguirá. Comienza aquí. Ajusta según lo que aprendas.