spec 1.0 · normativo

Gobernanza

La gobernanza es lo que distingue una capa de contexto de un wiki. Su principio es el círculo: el acceso es igual, la autoridad no.

El círculo, de forma normativa#

Todos leen. Todos los participantes, personas y agentes por igual, con acceso a una capa de contexto MUST poder leerla entera. Una capa de contexto con lectura restringida por rol dentro de ella no es una capa de contexto compartida; donde distintas personas puedan leer distinto material, ese material corresponde a capas de contexto separadas (véase Límite de acceso, más abajo, y distribution.md).
Cualquiera propone. Cualquier participante, persona o agente, MAY proponer cambios a la capa de contexto. Las propuestas redactadas por agentes son de primera clase: un agente que descubre contexto ausente o equivocado mientras trabaja SHOULD proponer la corrección en el mismo conjunto de cambios que el trabajo que lo destapó. Una propuesta SHOULD llevar razones suficientes para que quien revisa entienda su intención y su efecto esperado; esas razones son lo mínimo que una persona necesita para aprobar. Leji 1.0 no define un protocolo de evidencia generalizado (véase Alcance de la 1.0).
Las personas aprueban. Todo cambio a la capa de contexto MUST ser aprobado por una persona antes de volverse canónico. La aprobación pasa por el mecanismo de revisión que el repositorio ya tiene (los pull requests); Leji no introduce ningún proceso aparte. La participación MAY ocurrir a través de cualquier interfaz, pero la aprobación canónica MUST ser un registro de revisión auditable en ese mecanismo: atribuible a la persona que aprueba y ligado al conjunto de cambios bajo revisión. Una aprobación expresada solo en una discusión externa, en un chat, en el estado de un ticket o en los comentarios de un documento no cuenta hasta que se convierte en un registro así; replicarla en un comentario no basta. Ampliar cómo participan las personas nunca mueve dónde se registra la autoridad.

Requisitos#

Responsabilidad, no autoría. El manifiesto MUST nombrar un responsable principal (owners.primary) y MAY nombrar un responsable de continuidad (owners.continuity): una persona distinta que asume la misma responsabilidad cuando el principal no está disponible o se marcha. Una adopción asistida SHOULD nombrar al responsable de continuidad antes de que la ayuda externa se retire; una capa de contexto en solitario MAY no tener ninguno, lo cual señala con honestidad que no tiene sucesión. Los responsables son personas que responden: un agente propone y revisa, pero nunca es responsable, y nombrar de nuevo al principal como continuidad no aporta ninguna. El responsable responde de la salud de la capa de contexto: de que se mantenga vigente, de que se pode el contenido desactualizado o contradictorio y de que cada área tenga a alguien que la cuide. Los responsables no son curadores. El contenido lo escribe y lo mantiene cierto el círculo entero según trabaja; concentrar eso en un solo guardián es el cuello de botella que este modelo existe para evitar.
Alcance de la revisión. Los cambios en la capa de contexto SHOULD revisarlos las personas más cercanas al contenido afectado, los responsables de área, sin canalizarlos a través de un único guardián. La responsabilidad de área es el mapa de propiedad que el repositorio ya tiene (un archivo CODEOWNERS, una convención del equipo), no un campo nuevo del manifiesto; Leji lo reutiliza igual que reutiliza los pull requests para la aprobación. El responsable principal responde de que cada área tenga uno. La revisión pregunta más que «¿esto es cierto?»: por qué esto corresponde a la capa de contexto, quién se apoyará en ello, qué demuestra que se sostiene y cuándo habría que revisarlo. Un cambio que no puede responder a eso es un enlace o una nota, no contexto canónico. La pregunta permanente para cualquier conjunto de cambios es ¿este cambio alteró el contexto?; si la respuesta es sí, el delta de contexto corresponde al mismo conjunto de cambios.
Inclusión y retirada. Proponer es abierto; incluir no lo es. El contenido corresponde a la capa de contexto solo si cambia cómo se hará el trabajo futuro: fija una restricción, codifica una decisión, define una interfaz o un límite de responsabilidad, o corta un error repetido. Todo lo demás se enlaza, no se absorbe. La capa de contexto MUST tener una vía de retirada tan deliberada como su vía de aprobación: el contenido desactualizado, sustituido y duplicado se poda en conjuntos de cambios revisados ordinarios, y podar forma parte del deber de cada responsable de área, no es un proyecto de limpieza aparte. Una capa de contexto que solo crece es una que se pudre mientras pasa la revisión. La guía duradera SHOULD superar la regla de probado dos veces (según content-categories.md): una corrección puntual puede integrarse, pero una norma se vuelve canónica solo después de haberse sostenido en al menos dos tareas reales. Capture lo que es cierto, no lo que se espera.
Disciplina del registro de cambios. A partir de la conformidad indexed, todo cambio aprobado de la capa de contexto MUST anexar una entrada al registro de cambios legible por máquinas, según machine-readable-surface.md.
Vigencia. La vigencia es un mecanismo de intención: los documentos de intención y los perfiles de agente SHOULD llevar horizontes de revisión (freshness.reviewAfter en las entradas de índice y en los perfiles), y un registro no lleva ninguno (su fecha es su actualidad, según content-categories.md; un horizonte declarado sobre un registro es un error de validación). El utillaje SHOULD informar del contenido de intención cuyo horizonte ha pasado, y MUST NOT tratar en silencio como vigente el contenido desactualizado. Un lector que carga contexto para una tarea MUST exponer, en la salida de esa tarea, cualquier elemento cargado cuyo horizonte de revisión haya pasado, para que lo desactualizado le resulte visible a la persona en vez de quedar enterrado. Que el siguiente registro esperado de una serie operativa vaya con retraso es una noción distinta (actualidad de flujo); la 1.0 la nombra y no define mecanismo alguno para ella. El contexto requerido de una tarea es la unión del conjunto de carga incondicional del perfil de arranque, el requiredRead del perfil de agente activo y la porción que el algoritmo de enrutamiento por tarea selecciona para la tarea (sus decisiones vivas enrutadas y sus documentos gobernados de intención enrutados, más cualquier registro que las rutas de la tarea seleccionen directamente, según machine-readable-surface.md). Cuando el horizonte de un elemento requerido ha expirado, el lector MUST detenerse o preguntar en vez de seguir adelante con él; actuar sobre contexto que se sabe pasado de revisión es el fallo de desactualización silenciosa que esta regla existe para evitar. Un elemento desactualizado que no sea requerido MAY usarse haciendo constar que lo está. En la conformidad governed, los horizontes de vigencia MUST estar declarados y comprobados (según la lista de comprobación de conformidad, basta con una comprobación que solo informe); ejecutar la comprobación en integración continua es RECOMMENDED. La vigencia de revisión (lo anterior) es distinta de la actualidad de la copia de trabajo: si la copia que sostiene un lector coincide con el repositorio canónico. Un lector establece la actualidad de la copia de trabajo a partir del sistema de control de versiones (git); el árbol de trabajo solo está al día respecto a la revisión que tiene extraída, y el utillaje MUST NOT tratar en silencio como vigente una copia sin verificar. Un lector que alcanza la capa de contexto como contenido de archivos sueltos, sin árbol de trabajo git accesible ni metadatos de versión (contenido subido o sincronizado a otra interfaz, sin el repositorio), MUST tratar la actualidad de la copia de trabajo como desconocida en vez de como vigente.
El contenido canónico vive en la capa de contexto. El conocimiento que gobierna cómo se hace el trabajo MUST NOT existir únicamente en un archivo de configuración de proveedor, en un hilo de chat o en las notas de una persona. Si gobierna el trabajo, corresponde a la capa de contexto, bajo revisión.

Límite de acceso#

Leji no define mecanismo de control de acceso alguno propio. El acceso a una capa de contexto lo gobierna el sistema de control de versiones (git) y la plataforma donde vive el repositorio: los permisos del anfitrión del repositorio y el sistema de archivos o la unidad compartida que expone el árbol de trabajo. La unidad de acceso es la capa de contexto.

Una capa de contexto MAY vivir en un repositorio con control de acceso. Leji no concede, comprueba ni aplica ese acceso; lo hacen el sistema de control de versiones y su anfitrión.
Una capa de contexto conforme MUST NOT exigir lectura restringida por rol dentro de sí misma. «Todos leen» se acota a la audiencia de una capa de contexto: todo aquel a quien el sistema de control de versiones admite lee toda esa capa de contexto.
El contenido que necesita una audiencia más estrecha (un contexto de dirección, de finanzas, de seguridad o de respuesta a incidentes) MUST vivir en una capa de contexto separada, con su propio repositorio, manifiesto, responsable y proceso de revisión y aprobación, con permisos del sistema de control de versiones. El contexto restringido es una capa de contexto separada, nunca una región restringida de una compartida.
Componer una capa restringida dentro del contexto de otro equipo es el caso de la federación, con las reglas adicionales para montajes restringidos de distribution.md.

El modelo de mantenimiento (no normativo)#

La capa de contexto se mantiene cambio a cambio, como parte del trabajo que ya se iba a realizar: una tarea descubre contexto ausente o equivocado; la corrección pasa por el mismo conjunto de cambios revisado; el registro de cambios lo anota. No hay un sprint de documentación separado, ni hace falta que lo haya. Un contexto equivocado produce resultados equivocados que alguien detecta ese mismo día; eso, junto con la revisión y la integración continua de la mecánica, constituye todo el sistema de forzado.

Esa realimentación rápida detecta pronto el contenido equivocado. La acumulación lenta, el contenido que es meramente mediocre o redundante, la detectan el listón de inclusión y la vía de retirada de arriba, aplicados por las personas responsables de cada área. Eso es curación, y Leji la distribuye a propósito. Un curador único parece la forma segura de sostener la calidad y es lo contrario: se convierte en la vía más lenta del sistema, los cambios se le encolan o lo esquivan, y sostiene menos contexto del que sostienen las personas expertas de cada área. La capa de contexto o se atasca o se bifurca. Que cada responsable de área pode y filtre su propia porción es lo que mantiene toda la capa de contexto pequeña y cierta sin un punto de estrangulamiento. El responsable vela por la salud del sistema; el círculo, por el contenido.