La especificación Leji

pull request

La especificación Leji

Leji es una especificación abierta para la capa de contexto compartida de los equipos nativos de IA. Define cómo almacena, gobierna, carga y mantiene un equipo el contexto que pertenece al repositorio y que tanto las personas como los agentes de IA consultan en cada tarea.

Principios (no normativo)#

1. Intención antes que instrucciones. Leji recoge intención duradera (qué significan las cosas, qué debe cumplirse, por qué es así) en lugar de instrucciones imperativas atadas a cada proveedor. Las personas y los agentes derivan sus acciones de la intención declarada más el contexto de la tarea.
2. Un círculo, no un escalafón. Los flujos persona-a-persona, persona-a-IA y persona-a-IA-a-persona son de primera clase alrededor de una única capa de contexto compartida. El acceso es igual, la autoridad no: todo el que tiene acceso a una capa de contexto la lee entera, cualquiera propone y las personas aprueban. La participación depende del rol, no de la herramienta: quien nunca toca git directamente es igual de primera clase dentro del círculo. El acceso lo concede el sistema de control de versiones, no Leji; el círculo se acota a la audiencia de una capa de contexto.
3. Mecanismo antes que buena voluntad. El contexto compartido se degrada por defecto: la realidad avanza, los documentos no, y nada obliga a un wiki a estar al día. Los mecanismos de forzado de Leji son mecánicos, no de buena voluntad: los cambios pasan por el mismo proceso de revisión y aprobación que el código, el utillaje falla ante desviaciones mecánicas, los horizontes de vigencia señalan lo que ha envejecido y el contenido desactualizado nunca se trata en silencio como si estuviera vigente (de forma normativa, governance.md → Vigencia).

El resto de esta especificación es la consecuencia normativa de esos tres principios.

Lenguaje de conformidad#

Las palabras clave MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY y OPTIONAL en esta especificación deben interpretarse como se describe en el RFC 2119.

Cómo citar esta especificación (no normativo)#

Cite una sección por su título y la versión de la especificación, con un enlace permanente al ancla de la sección. En el sitio de la especificación, cada encabezado revela su ancla al pasar el cursor.

• Formato: Leji 1.0, §Sección: https://leji.org/spec/<document>/#<anchor>
• Ejemplo: Leji 1.0, §The circle, normatively: https://leji.org/spec/governance/#the-circle-normatively

Cite siempre la versión (Leji 1.0): los cambios incompatibles se publican como una nueva versión mayor, de modo que una cita fijada a una versión sigue siendo exacta cuando la especificación evoluciona.

Vocabulario#

Estos términos se usan de forma consistente en todos los documentos normativos:

La jerarquía puede resumirse en una línea: un modelo impulsa a un agente; un agente opera a través de un host de agente e invoca herramientas; la capa de contexto se dirige a agentes y hosts, nunca a modelos directamente. La especificación es agnóstica en cada nivel de esa pila: cualquier modelo puede impulsar cualquier agente, que puede operar a través de cualquier host y leer la misma capa de contexto. «LLM» queda deliberadamente fuera de este vocabulario: designa una sola clase de modelo, mientras que la especificación es agnóstica respecto al modelo por ese mismo principio.

Límite de alcance. Leji 1.0 gobierna a los agentes y a los hosts de agente que cargan contexto del repositorio. La IA no agéntica (autocompletado, sugerencias en línea, chat sin contexto del repositorio) queda fuera del alcance normativo, salvo cuando opera como parte de un host de agente que carga la capa de contexto.

Documentos normativos#

En orden de lectura:

Los esquemas JSON de ../schemas/ son normativos para los artefactos legibles por máquinas. Los documentos de ../rationale/ y ../adoption/ no son normativos.

Alcance de la 1.0#

Dentro del alcance: aportar contexto, fijar restricciones, registrar decisiones, revisar cambios y capturar patrones reutilizables; la conexión agnóstica respecto al agente y los adaptadores de proveedor (someramente); la semántica de responsabilidad y continuidad (someramente).

Límite de extensión. Leji 1.0 especifica la capa de contexto compartida canónica: cómo se escribe, se posee, se versiona, se propone, se aprueba, se indexa y se lee el contexto de un equipo. Deliberadamente no especifica los protocolos de ejecución que operan alrededor de esa capa de contexto: sobres de tarea, un protocolo de evidencia generalizado, el traspaso entre agentes, los protocolos de permisos de herramientas y la orquestación. Son protocolos de extensión, no requisitos previos: una capa de contexto conforme con 1.0 MUST seguir siendo útil sin ellos, y una implementación MUST NOT exigirlos para leer, proponer, revisar, aprobar o validar la capa de contexto. Completan el lenguaje a medida que la práctica real los demuestra; no se inventan en abstracto.

Leji no es un lenguaje de programación, ni un DSL, ni un entorno de ejecución, ni un SaaS. Son convenciones de markdown, esquemas JSON pequeños y semántica de gobernanza.

pull request

La capa de contexto

Una capa de contexto Leji es un conjunto versionado y gobernado de documentos legibles por personas que recoge cómo concibe un equipo su trabajo: el lenguaje del dominio, las invariantes del sistema, las convenciones, las salvaguardas y los registros de decisión. Las personas y los agentes la consultan durante el trabajo real, y ambos proponen cambios a través del mismo proceso de revisión y aprobación. Se mantiene bajo control de versiones para que el historial, la actualidad y la aprobación sigan siendo verificables; la mecánica se detalla en Requisitos, más abajo, y Participación explica quién participa y cómo.

Participación#

La participación en una capa de contexto depende del rol, no de la herramienta. Leer, proponer, revisar y aprobar ocurren a través de cualquier interfaz que preserve la semántica de revisión y aprobación del repositorio; no se exige conocer git ni la línea de comandos para participar.

• Todo el que tiene acceso lee. Acceso significa acceso práctico a través de las herramientas normales del equipo, no acceso a la shell del repositorio.
• Cualquiera propone; las personas aprueban. Una propuesta es una petición intencionada de cambiar la capa de contexto. MAY estar redactada directamente por una persona, generada por un agente a partir de la petición de una persona, o generada por un agente a partir del trabajo observado. En la práctica los agentes redactan la mayoría de los cambios de contexto; la aportación humana irreductible es la gobernanza: proponer la intención y aprobar lo que se vuelve canónico. Quien aprueba un cambio responde de su significado y sus consecuencias, no de operar personalmente el sistema de control de versiones.
• Significado humano, superficie legible por máquinas. Los documentos legibles por personas son la fuente normativa del contexto operativo de un equipo. Los archivos legibles por máquinas (manifiesto, índice, registro de cambios) existen para que las herramientas localicen, indexen, validen y sincronicen ese significado; nunca lo sustituyen.

La forma normativa de estos flujos, el círculo (todos leen, cualquiera propone, las personas aprueban), se define en governance.md.

Cómo se lee un registro#

El contenido gobernado viene en dos clases, definidas en content-categories.md: la intención, que se mantiene como verdad presente, y los registros, evidencia fechada que el estado posterior sustituye en lugar de corregir. Ambas están igualmente gobernadas; lo que cambia es qué puede hacer un lector con lo que carga. Un lector MUST NOT tratar un registro como intención vigente: un registro tiene el peso de evidencia cierta dentro de su límite declarado, y un lector que presenta lo que afirma un registro como el estado presente de las cosas, sin decirlo, está fabricando una actualidad que el documento no tiene. Esto refleja la regla del modo degradado que aparece más abajo: en ambos casos, la obligación del lector es saber, y decir, qué clase de actualidad tiene entre manos.

Requisitos#

1. La capa de contexto MUST vivir en un repositorio git y MUST versionarse junto con el trabajo que describe (el mismo repositorio, o un repositorio de contexto dedicado consumido según distribution.md). El repositorio git es lo que hace verificables el historial de la capa de contexto, la actualidad de la copia de trabajo y la integridad de solo anexión del registro de cambios; el utillaje conforme deriva las tres de él. Leer la capa de contexto sin ese repositorio es un modo admitido pero degradado, definido en Modos de lectura.

2. Un repositorio que adopta Leji MUST llevar un archivo de manifiesto, leji.json, en la raíz del repositorio, válido frente a context-manifest.schema.json. El manifiesto es el punto de entrada para las máquinas: declara la versión de la especificación (la clave autonombrada leji), el nombre de la capa de contexto, la raíz del contexto, la ruta del perfil de arranque, las asignaciones de categoría, una declaración opcional de conformidad y la responsabilidad. MAY llevar además un mapa agents que vincule identificadores de rol (por ejemplo thought-partner, reviewer) con documentos de perfil de agente: los protocolos convocan roles; el mapa decide quién los ocupa. El mapa es un directorio de roles, no un orden de carga: una vinculación, incluida la de la clave default, nunca provoca la lectura de un perfil; solo la sección de carga del perfil de arranque lo hace.

3. El manifiesto MAY declarar actores: participantes con nombre que pueden ocupar roles. Cada actor declara los roles para los que es elegible y una plantilla de comando por rol. Que el comando se indexe por rol es justo lo importante: un mismo actor puede exigir una invocación distinta según el rol que ocupe, de modo que un único comando por actor no bastaría para expresarlo. Los roles declarados de un actor y las claves de sus comandos MUST ser el mismo conjunto. Donde un rol tiene actores, el perfil de agente vinculado a ese rol MUST NOT declarar además invocation: dos comandos autoritativos sin precedencia declarada son una contradicción, y la capa la resuelve declarando el comando en un solo lugar. Los actores son opcionales y la mayoría de las capas no necesitan ninguno. Se justifican cuando un rol tiene más de un actor elegible, o cuando un actor necesita una invocación distinta según el rol que ocupe; cualquiera de las dos razones basta, y un rol cuyo único actor necesita un solo comando queda servido por el host y el invocation del propio perfil. Declarar un actor no concede autoridad alguna: dice a quién se puede pedir que ocupe un rol, nunca quién puede aprobar.

   Las plantillas de comando, dondequiera que aparezcan (los valores de commands de un actor y el invocation.command de un perfil de agente), siguen una sola regla. Una plantilla es una línea de comandos para la shell que elija quien invoca; una interacción que no tenga forma de shell (una llamada argv estructurada, un lanzamiento en proceso) no es representable con estos campos en la línea 1.0. Toda plantilla MUST llevar el marcador de posición <prompt>, y cada aparición MUST constituir su propia palabra de shell sin comillas en posición de argumento, nunca dentro de comillas ni unida a otro texto. La sustitución es de una sola pasada: las apariciones presentes en la plantilla redactada se reemplazan simultáneamente, exactamente una vez, de modo que la cadena literal <prompt> dentro del texto del prompt sigue siendo datos y nunca se vuelve a expandir. Quien invoca es responsable de la entrega, y el contrato es el resultado exigido, no el algoritmo de entrecomillado: cada aparición produce exactamente un argumento cuyo valor es igual al texto del prompt, sin que nada de él se evalúe como sintaxis de shell. Lo que verifican los esquemas es la presencia de un punto de sustitución; exigir la colocación y la entrega corresponde a esta regla; honrarlas, a quien invoca.

4. El manifiesto MUST declarar una raíz del contexto (rootPath). El valor por defecto RECOMMENDED es docs/. Todas las rutas de la capa de contexto son de estilo POSIX y relativas a la raíz del repositorio. rootPath declara dónde vive la capa de contexto; no cambia la base desde la que se resuelven las rutas que gobierna: las entradas del índice, las páginas fijadas, las rutas de los perfiles y toda otra ruta de todo artefacto Leji se resuelven desde la raíz del repositorio, incluidas las que repiten el prefijo de rootPath. El homepage, el logo y el favicon del visor son la excepción: se escriben relativos a la raíz del contexto, y también se acepta una ruta relativa a la raíz del repositorio que quede bajo ella. Las rutas de categoría y de machine SHOULD quedar bajo rootPath; los validadores avisan cuando no es así.

5. La capa de contexto MUST tener un perfil de arranque conforme a boot-profile.md. La ubicación por defecto RECOMMENDED es docs/boot-profile.md; el bootProfilePath del manifiesto declara la ubicación real.

6. El contenido de la capa de contexto MUST ser legible por personas ante todo. Markdown es el formato RECOMMENDED para la prosa; los metadatos estructurados usan frontmatter YAML o los artefactos JSON definidos en machine-readable-surface.md. Un documento que solo una máquina puede leer no pertenece a la capa de contexto.

7. La capa de contexto MUST tener un responsable con nombre (owners.primary en el manifiesto): una persona que responde de su actualidad. Las capas de contexto sin responsable se pudren.

Modos de lectura: canónico y degradado#

Una capa de contexto se lee en dos modos; un lector MUST saber en cuál está, porque las garantías difieren. Un lector determina su modo a partir de lo que puede resolver: un leji.json alcanzable en la raíz del repositorio y o bien un árbol de trabajo git o bien la identidad de revisión del repositorio en la plataforma anfitriona es canónico; el contenido alcanzado como archivos sueltos sin ninguna de las dos cosas es degradado.

1. Canónico. El lector resuelve la capa de contexto a través de su repositorio git: una copia de trabajo, o la vista del repositorio en la plataforma anfitriona. El historial, la actualidad de la copia de trabajo y la integridad del registro de cambios son verificables, y se sabe que el contenido aprobado está vigente en la revisión leída.
2. Degradado. El lector alcanza la capa de contexto como contenido de archivos sueltos, sin árbol de trabajo git accesible ni metadatos de versión: archivos subidos, sincronizados o copiados a otra interfaz sin el repositorio. La lectura de archivos sueltos es de primera clase para leer (los documentos son legibles por personas por requisito, y el registro de cambios legible por máquinas sigue transmitiendo la actualidad declarada), pero un lector degradado MUST tratar la actualidad de la copia de trabajo y el estado de aprobación como desconocidos, nunca como vigentes (véase governance.md, Vigencia). El registro de cambios es la superficie portátil de actualidad declarada en este modo; por sí solo no establece que la copia coincida con el repositorio canónico.

La lectura degradada amplía quién y qué puede consumir una capa de contexto; nunca es una vía hacia la autoridad canónica. Un cambio se vuelve canónico únicamente a través del proceso de revisión y aprobación respaldado por git, y una copia degradada no puede satisfacer las comprobaciones en modo canónico de las que depende la federación (actualidad de la fijación, estado de fijación desactualizada, integridad de la responsabilidad y acceso a montajes restringidos, según distribution.md).

La regla del adaptador de proveedor#

Los archivos de configuración de los hosts de agente (por ejemplo CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .cursor/rules, .windsurfrules, .github/copilot-instructions.md):

1. MUST NOT guardar contenido canónico de la capa de contexto.
2. Si existen, MUST redirigir al perfil de arranque (normalmente un puntero de una línea).
3. MAY llevar mecánica específica del host que no tenga significado fuera de ese host de agente (selección de modelo, ajustes del ejecutor), siempre que allí no viva conocimiento del equipo.
4. El utillaje descubre qué puntos de entrada comprobar a partir de dos fuentes: la lista opcional vendorAdapters del manifiesto y un conjunto bien conocido publicado (los archivos nombrados arriba). La lista de ejemplo de arriba es ese conjunto bien conocido para esta línea; un host cuyo punto de entrada no figure en él se comprueba solo cuando el manifiesto lo nombra en vendorAdapters.

Las convenciones de punto de entrada que ya existen le dicen a un host de agente dónde mirar; Leji define qué encuentra allí el agente. Una sola fuente de verdad, leída por todos los participantes.

Lo que la capa de contexto no es (no normativo)#

• No es un wiki. Nada obliga a un wiki a estar al día. La capa de contexto sigue viva porque los agentes la leen en cada tarea (un contexto equivocado produce resultados equivocados que se notan de inmediato), porque los cambios pasan por revisión igual que el código y porque el utillaje hace visible lo desactualizado.
• No es documentación en el sentido tradicional. La documentación describe a posteriori lo que hace el sistema. La capa de contexto refleja cómo piensa el equipo en el presente, y tanto las personas como los agentes la consultan continuamente.
• No es una plantilla que se importa. El contexto prestado se queda obsoleto de inmediato. El valor de una capa de contexto está en que es la representación propia del equipo; Leji estandariza la forma y la gobernanza, no el contenido.

pull request

Categorías de contenido

Leji define cinco categorías lógicas de contenido. Clasifican para qué sirve un documento, no dónde se encuentra: los nombres de categoría son identificadores estables que utilizan el manifiesto, el índice y el utillaje. El equipo decide cómo llamar a los directorios.

Las cinco categorías#

Intención y registros#

Todo documento gobernado es o bien intención o bien un registro, con independencia de su categoría:

• La intención es verdad presente mantenida: glosarios, invariantes, convenciones, salvaguardas. Los lectores confían en ella como vigente, así que cuando la realidad se mueve, el documento se corrige. La intención es la razón de ser de los horizontes de revisión y del mecanismo de vigencia (véase governance.md).
• Un registro preserva afirmaciones dentro de un límite temporal o de evento explícito: estados, evaluaciones, libros de asientos, informes, resultados de reuniones, archivos históricos. El estado posterior sustituye a un registro en vez de corregirlo; el original sigue siendo un relato válido de su momento. La superficie de actualidad de un registro es su fecha, nunca un horizonte de revisión.

La prueba de clasificación es una sola pregunta: si información posterior contradice este documento, ¿hay que corregirlo porque los lectores confían en él como vigente, o la nueva información lo sustituye mientras el original sigue siendo un relato válido de su momento? Corregir significa intención; sustituir significa registro.

Un registro se gobierna exactamente igual que la intención: se indexa, se revisa, tiene responsable y se enruta. Lo que cambia es qué puede hacer un lector con él: un lector MUST NOT tratar un registro como intención vigente; es evidencia fechada (véase context-layer.md, Cómo se lee un registro). Los registros de decisión son el subtipo formal de registro: son registros por naturaleza, con su propio esquema y ciclo de vida según decisions.md.

Algunas cuestiones sobre los registros quedan deliberadamente fuera de la 1.0 y se reconocen en lugar de ocultarse: no existe una noción para máquinas de serie de registros (por lo que el utillaje nunca certifica cuál es «el último»), no hay mecanismo de actualidad de flujo (si el siguiente registro esperado va con retraso) y no hay clases por sección para documentos que mezclan de forma sustancial contenido de intención y de registro. Un documento mixto SHOULD dividirse; donde dividirlo resulte desproporcionado, clasifíquelo por el contrato en el que se apoyan principalmente sus lectores. El contenido que honestamente no encaja en ninguna categoría se queda como referencia; no se promete que la clasificación esté libre de criterio.

Requisitos#

1. El manifiesto MUST asignar cada categoría que declare a uno o más archivos de índice relativos a la raíz del repositorio (categories.<id>.indexes); cada archivo de índice SHOULD quedar bajo la raíz del contexto declarada, según context-layer.md. Un archivo de índice declara inclusión, no reubica: el contenido se queda donde el equipo ya lo guarda (por ejemplo business/, technology/, architecture/), y un mismo directorio puede aportar documentos a más de una categoría sin renombrar nada.
2. Un archivo de índice es markdown curado que lleva uno o más bloques de código delimitados con el identificador leji-index. Un bloque abre con una línea de tres o más comillas invertidas seguidas de la cadena de información del bloque y cierra con la siguiente línea de tres o más comillas invertidas; el número de comillas invertidas de la valla de cierre no tiene por qué coincidir con el de la de apertura. Solo tres cadenas de información son válidas: leji-index (un bloque de intención), leji-index intent (lo mismo, explícito) y leji-index record (un bloque de registros, cuyas entradas se resuelven como registros). Cualquier otro token tras leji-index es un error de análisis, nunca se ignora en silencio: la gramática es finita por diseño. Cada bloque enumera contenido a razón de una entrada por línea con la forma - path: <repository-root-relative-path>, donde una ruta es un directorio (su markdown se incluye recursivamente) o un único archivo markdown. Una ruta MUST ser POSIX relativa a la raíz del repositorio: una / inicial, un segmento .. o una barra invertida son inválidos y se rechazan. Las líneas en blanco y las líneas completas de comentario # se ignoran, y una entrada MAY llevar al final un # comentario precedido de espacio en blanco. En esta gramática el espacio en blanco es el espacio ASCII (U+0020) y el tabulador (U+0009) y nada más, en todos los sitios donde la gramática lo consulta: alrededor de las comillas invertidas de la valla y de la cadena de información, como relleno inicial y final de una línea de entrada, y antes del # que abre un comentario final. Una marca de orden de bytes UTF-8 inicial se elimina antes de analizar. Las líneas se separan por LF tolerando un CR final, y el archivo es UTF-8. Las implementaciones MUST NOT usar aquí una clase de espacio en blanco del entorno de ejecución: cualquier otro carácter que un entorno de ejecución clasifique como espacio en blanco, entre ellos U+0085 y U+00A0, es contenido normal de la ruta, de modo que una entrada cuya ruta lleve uno se informa como ausente en vez de recortarse en silencio. Los bloques leji-mounts de boot-profile.md están congelados sobre el mismo alfabeto, así que un único escáner lee ambas gramáticas y tres implementaciones no pueden discrepar sobre si una valla existe siquiera. Varios bloques en un mismo archivo se concatenan en el orden del documento. Se permiten prosa y encabezados alrededor de los bloques, de modo que un archivo de índice sirve también como mapa legible de la categoría. El barrido va por líneas y no consulta la estructura markdown: una línea que lleve tres o más comillas invertidas y la etiqueta, tras un sangrado opcional de espacios o tabuladores, abre un bloque real esté donde esté en el documento, incluso dentro de una valla más larga de ejemplo o dentro de un elemento de lista. Un ejemplo destinado a ilustrar y no a declarar se delimita, por tanto, con una etiqueta distinta, nunca con un token de más tras leji-index: la etiqueta es lo que el escáner compara, de modo que leji-index example abre un bloque real e informa de un error de análisis, mientras que una valla etiquetada text no abre nada. La ubicación RECOMMENDED es context/<id>.md bajo la raíz del contexto; la ubicación es configurable y el utillaje nunca la fija en el código.
3. Una capa de contexto MUST asignar al menos domain o system, más decisions, para declarar cualquier nivel de conformidad (véase conformance.md), y el mínimo poblado de domain/system MUST incluir al menos un documento de intención: una capa de contexto hecha solo de registros preserva historia pero no aporta contexto operativo. Las demás categorías se acumulan a medida que el equipo se topa con preguntas reales; una categoría vacía (aquella cuyos archivos de índice no resuelven a ningún documento) MUST NOT asignarse para cumplir una lista de comprobación.
4. Un documento resuelve a exactamente una categoría y una clase. Las entradas de índice son selectores, y la resolución sigue la especificidad del selector: un selector directo de archivo gana a cualquier selector de directorio, y un selector de directorio más profundo gana a un selector de directorio ancestro. El selector más específico que cubre un documento determina su categoría y la clase de su bloque; un documento al que cubre un selector más amplio pero que gana uno más específico sencillamente no es contenido de ese selector más amplio (así es como se expresa, sin mover nada, un archivo que se mantiene al día dentro de un directorio de registros, o el registro de decisiones de un equipo dentro de un árbol asignado más amplio). Selectores de igual especificidad que discrepan en categoría o clase son un error, nunca se resuelven por el orden del índice; asignaciones idénticas de igual especificidad resuelven una sola vez, mientras que una entrada literalmente duplicada dentro de un mismo archivo de índice se rechaza. El utillaje SHOULD señalar un selector cuyos documentos cubiertos hayan sido ganados todos por selectores más específicos (un selector eclipsado): peso muerto en el mapa curado, nunca un error. Por lo demás la resolución es determinista: una entrada de directorio se expande a su markdown en orden lexicográfico POSIX (por punto de código Unicode; se RECOMMENDED que las rutas se mantengan en ASCII para que el orden no sea ambiguo entre implementaciones), y cualquier ruta cuya ubicación real (tras resolver los enlaces simbólicos) se escape de la raíz del repositorio se excluye en vez de seguirse. Las entradas de índice (véase machine-readable-surface.md) llevan el identificador de categoría y la clase.
5. Un documento MAY declarar su clase en el frontmatter (kind: intent o kind: record); el frontmatter prevalece sobre la clase de bloque del selector ganador y nunca sobre la categoría. Cualquier otro valor de kind es un error. Los registros de decisión no llevan clave kind (su esquema es cerrado y son registros por naturaleza). Un registro MAY llevar una date en el frontmatter (YYYY-MM-DD); el utillaje lee la fecha de un registro solo de ese campo, nunca de la prosa, de convenciones de encabezado o de nombres de archivo. Un registro MUST NOT llevar freshness.reviewAfter (un horizonte de revisión es un mecanismo de intención; sobre un registro promete una actualidad que el documento no puede tener, y es un error).
6. El contenido de práctica que describe patrones de prompt o de flujo de trabajo SHOULD capturarse solo después de que el patrón haya funcionado al menos dos veces (la regla de probado dos veces). La captura prematura es la forma en que los directorios de práctica se llenan de aspiraciones.

Notas (no normativo)#

No todas las categorías tienen que estar presentes desde el primer día. La capa de contexto mínima viable es aquella en la que se apoya de verdad el trabajo del primer mes. Las categorías permiten que una persona o un agente se pregunten «¿qué clase de verdad es esta?» y carguen solo la porción pertinente para la tarea, en lugar del árbol completo.

Las dos clases existen porque la documentación de un repositorio real son dos corpus entrelazados con modelos de verdad distintos, y forzar la mitad operativa bajo la semántica de la intención falla por ambos lados: promesas de vigencia que no se pueden cumplir, o la mayoría del repositorio desterrada fuera de la gobernanza. Una forma desarrollada, con una excepción de intención dentro de un directorio de registros:

# Contexto de dominio

```leji-index
- path: docs/glossary.md
```

El estado operativo se gobierna como registros; la política de escalado se queda como intención.

```leji-index record
- path: docs/operations/
```

```leji-index intent
- path: docs/operations/escalation-policy.md
```

pull request

El perfil de arranque

El perfil de arranque es el punto de entrada de la capa de contexto, independiente del agente: un único documento legible por personas que sirve de punto de partida a cualquier persona o host de agente. Responde a «qué es esta capa de contexto, qué debo cargar y cómo debo comportarme aquí».

Requisitos#

1. La capa de contexto MUST tener exactamente un perfil de arranque, situado en la ruta que declara bootProfilePath en el manifiesto. El valor por defecto RECOMMENDED es docs/boot-profile.md.

2. El perfil de arranque MUST ser markdown simple, legible por una persona sin utillaje alguno. MUST NOT depender de la sintaxis de configuración de ningún proveedor.

3. El perfil de arranque MUST cubrir:

   • Identidad: qué es este repositorio o producto, en un párrafo.
   • Carga: qué contexto leer para cada clase de tarea. Esto MUST dar un conjunto incondicional (qué leer antes de cualquier tarea) y después selectores por tipo de tarea que enruten por ruta, por categoría o a través del índice del contexto, más un mecanismo de reserva definido para una tarea que no case con ningún selector. Enunciado en lenguaje de tarea, esto es la expresión, en el nivel del perfil de arranque, del algoritmo de enrutamiento por tarea (machine-readable-surface.md); seguirlo no exige conocer ese algoritmo.
   • Postura: lo que se espera del agente al operar (cuándo seguir adelante, cuándo preguntar, qué no hacer nunca). Esto MAY aportarse por referencia a contenido de gobernanza o a un perfil de agente central.

4. El perfil de arranque SHOULD enlazar al manifiesto, al índice (si existe) y a los perfiles de agente (si existen), de modo que un agente que entre por cualquier host pueda descubrir toda la superficie legible por máquinas.

5. El perfil de arranque MUST hablar en lenguaje de tarea: nombra rutas literales y un orden de carga concreto, y seguirlo no exige conocer esta especificación. El manifiesto y los esquemas existen para el utillaje, no para los agentes; un perfil de arranque que exige alfabetización en la especificación para seguirse es un indicio de mala conformidad.

6. El perfil de arranque SHOULD enunciar los deberes de mantenimiento de la capa de contexto: dónde se registran sus cambios (el registro de cambios declarado) y cómo se capturan las decisiones (la ubicación declarada de los registros de decisión). Los validadores avisan cuando el perfil de arranque no menciona ninguno de los dos.

7. Los archivos de entrada de proveedor redirigen al perfil de arranque según la regla del adaptador de proveedor de context-layer.md.

8. El conjunto de carga incondicional del perfil de arranque (lo que dice leer antes de cualquier tarea) SHOULD acotarse a lo que toda tarea necesita. El contexto que solo necesitan algunas tareas SHOULD enrutarse por tarea, por categoría o mediante el índice en vez de precargarse; y los registros de decisión SHOULD enrutarse por sus affectedPaths / affectedCategories declarados en vez de cargarse como directorio completo, ya que se acumulan sin límite. Todo lo que esté en el conjunto incondicional se paga en cada tarea.

9. Hermanas federadas. Una capa de contexto que declara federation.mounts (según distribution.md) MUST exponer esas hermanas en el perfil de arranque de una forma comprobable por máquinas: uno o más bloques delimitados cuya cadena de información sea leji-mounts, colocados en cualquier punto del documento, cuyas entradas se concatenan en el orden del documento y llevan exactamente una entrada por montaje declarado. Una entrada nombra a la hermana, a su responsable, qué trae y cuándo leerla, estas dos últimas en el lenguaje de tarea de quien escribe. El ejemplo completo está debajo de los requisitos.

   La gramática es fija para que toda implementación la lea de forma idéntica. Un bloque abre con una línea de tres o más comillas invertidas seguidas de la cadena de información y cierra con la siguiente línea de tres o más comillas invertidas; el número de comillas invertidas de la valla de cierre no tiene por qué coincidir con el de la de apertura. La cadena de información es leji-mounts a secas; una valla que lleve cualquier token tras ella es un error, nunca una valla ignorada. Las líneas de valla MAY llevar sangrado y relleno de espacios o tabuladores, y los registros que hay entre ellas MUST NOT: un registro empieza en la columna 1 con - mount: , y sus campos van sangrados exactamente dos espacios ASCII. Dentro de un registro, owner, carries y read-when aparecen exactamente una vez cada uno, en cualquier orden; los campos desconocidos, los campos duplicados y los campos ausentes son errores. Un valor es el resto no vacío de su línea tras el prefijo key: , sin espacio ni tabulador inicial o final y sin ningún carácter de control o separador de línea. En esta gramática el espacio en blanco es el espacio ASCII (U+0020) y el tabulador (U+0009) y nada más, tanto en el sangrado y el relleno de la línea de valla como en una línea de contenido; las implementaciones MUST NOT usar aquí una clase de espacio en blanco del entorno de ejecución, ya que esas discrepan sobre caracteres como U+0085 y U+00A0 y discreparían sobre si un bloque existe siquiera. Una marca de orden de bytes UTF-8 inicial se elimina antes de analizar. Las líneas se separan por LF tolerando un CR final, las líneas en blanco y las líneas completas que empiezan por # se ignoran (como en los bloques de índice de categoría de content-categories.md), y el archivo es UTF-8. El barrido va por líneas y no consulta la estructura markdown: una línea que lleve tres o más comillas invertidas y la etiqueta, tras un sangrado opcional de espacios o tabuladores, abre un bloque real esté donde esté en el documento, incluso dentro de una valla más larga de ejemplo o dentro de un elemento de lista. Un ejemplo destinado a ilustrar y no a declarar se delimita, por tanto, con una etiqueta distinta, nunca con un token de más tras leji-mounts: la etiqueta es lo que el escáner compara, de modo que leji-mounts example abre un bloque real e informa de un error de análisis, mientras que una valla etiquetada text no abre nada. mount MUST coincidir con el name de un montaje declarado y owner MUST coincidir con el owner.name declarado de ese montaje, comparados como cadenas decodificadas; una entrada para un montaje no declarado, una segunda entrada para un mismo montaje y un montaje declarado sin entrada son todos errores. Una capa que no declara ningún montaje MUST NOT llevar un bloque leji-mounts.

   La ubicación de la hermana no es un elemento, y es deliberado: un montaje se materializa en una proyección local a la máquina y direccionada por contenido, de modo que un lector la resuelve con leji mounts locate <name> en vez de inferir una ruta (según distribution.md). La prosa que rodea al bloque SHOULD explicar el enrutamiento con naturalidad; el bloque es el núcleo comprobable, nunca un sustituto de esa prosa ni de la declaración en leji.json. Las hermanas montadas son fuentes distintas y con nombre, nunca se funden en las categorías de la anfitriona; el perfil de arranque encamina al agente hacia una hermana solo cuando la tarea casa con su enrutamiento o cuando el perfil lo exige. Lo que queda sin comprobar es deliberado: carries y read-when son texto libre, y su fidelidad a los metadatos de enrutamiento del montaje la atestigua el equipo en lugar de verificarla el utillaje, que comprueba la enumeración, la identidad y la presencia. Exponer aquí a las hermanas mantiene el descubrimiento de montajes dentro del punto de entrada en lenguaje de tarea del agente, de modo que seguir el requisito 5 sigue sin exigir leer el manifiesto.

Un bloque leji-mounts completo#

Una entrada, para una anfitriona que declara un único montaje llamado acme-product-context. El bloque va en la columna 1 del perfil de arranque, exactamente como se lee aquí; la valla exterior de cuatro comillas invertidas es el envoltorio de este documento y no forma parte de él.

```leji-mounts
- mount: acme-product-context
  owner: Equipo de producto
  carries: el lenguaje de dominio del lado de producto y las decisiones tras la superficie de cara al cliente
  read-when: una tarea toca el comportamiento del producto, la terminología de producto o la facturación
```

Perfiles de agente#

Una capa de contexto MAY definir perfiles específicos de rol (por ejemplo un perfil de revisor, un perfil de publicación, un perfil de QA) bajo un directorio declarado por machine.agentProfilesPath. Cada perfil:

1. MUST ser markdown con frontmatter YAML válido frente a agent-profile.schema.json.

2. MUST, una vez resuelta la herencia, llevar qué lee el rol en primer lugar (requiredRead) y cuándo debe detenerse y preguntar (mustAskWhen). Un perfil que declara inherits MAY omitir cualquiera de los dos allí donde su base lo aporte; un perfil que no lo declara MUST declarar ambos por sí mismo.

3. MAY declarar inherits, que es operativo en la línea 1.0: nombra exactamente otro perfil del conjunto de perfiles de la capa, cuyo role MUST ser core, y cuya postura y cuerpo extiende este perfil. El conjunto de perfiles de la capa lo forman todos los documentos bajo el machine.agentProfilesPath declarado junto con todos los documentos nombrados en el mapa agents del manifiesto, estén donde estén. La resolución es de un solo nivel, de modo que un perfil cuyo role sea core MUST NOT declarar inherits, y el destino nombrado MUST existir, MUST ser único por id y MUST NOT declarar inherits a su vez. La resolución compone:

   • Los arrays de postura (requiredRead, defaultContext, mustAskWhen, mustRefuseWhen): las entradas de la base en el orden en que fueron escritas, y después las del perfil derivado en el suyo, descartando las que la base ya lleve. El orden en que se escribieron es intención de carga, así que no se ordena nada.
   • Todos los demás campos (id, name, role, purpose, version, host, invocation, escalation, owners, freshness): los propios del perfil derivado, nunca heredados. inherits es una directiva de resolución y no forma parte, en sí misma, del perfil resuelto.
   • El cuerpo: ambos cuerpos son normativos, primero el de la base y después el del perfil derivado.

   Un consumidor que no pueda resolver un perfil heredado MUST NOT aplicar por su cuenta el archivo derivado; el archivo derivado es la mitad de un perfil, así que el consumidor lo informa como no admitido. Donde una condición de preguntar y una de rehusar se apliquen a la misma situación, manda rehusar.

   La resolución garantiza composición, no estrechamiento semántico: la prosa derivada que contradice o debilita a la base no es conforme, y ningún utillaje detecta una contradicción en lenguaje natural.

Los perfiles afinan qué carga un rol y cómo se comporta; no duplican contenido de la capa de contexto.

El host y el invocation opcionales de un perfil son la forma abreviada para un solo actor: dicen cómo interactuar con el único participante que ocupa este rol. Su command es una plantilla que sigue la misma regla que las plantillas de comando de los actores, incluidos el marcador de posición <prompt> y su colocación (véase context-layer.md, Requisitos). Donde un rol tiene más de un participante elegible, o donde el mismo participante necesita una invocación distinta según el rol que ocupe, eso lo lleva en su lugar el registro opcional actors del manifiesto (misma sección). Un rol usa un mecanismo o el otro, nunca ambos.

Notas (no normativo)#

El perfil de arranque es deliberadamente sencillo: un mapa y una postura, no una base de conocimiento. Si ocupa más de unas pocas pantallas, es señal de que el punto de entrada contiene material que corresponde a una categoría.

Este diseño protege frente a un modo de fallo concreto: la indirección. Cada salto entre el contexto inicial de un agente y la restricción real consume atención. Una capa de contexto bien implementada no necesita puntos de entrada de proveedor (la invocación puede apuntar directamente al perfil de arranque), y el perfil de arranque conduce directamente al contenido. La profundidad debe estar en los documentos de la capa de contexto, nunca en el recorrido hasta ellos.

Todo documento que el perfil de arranque manda leer antes de cualquier tarea se paga en cada tarea, así que el conjunto incondicional es el espacio más caro de la capa de contexto. Manténgalo en lo que sea genuinamente universal y encamine el resto a través de cargas por tipo de tarea, las categorías, el índice y el alcance que declara cada registro de decisión. El índice existe para que un agente pueda cargar la porción que necesita una tarea en vez del árbol entero; las decisiones se acumulan sin límite, así que se enrutan, nunca se precargan como directorio.

pull request

La superficie legible por máquinas

Cinco artefactos permiten que el utillaje lea la capa de contexto. El resto es prosa destinada a personas que los agentes también consultan; estos cinco artefactos constituyen el contrato sobre el que se construyen las herramientas.

Todas las ubicaciones salvo la del manifiesto se declaran en el manifiesto; la tabla muestra los valores por defecto.

Requisitos#

1. Manifiesto. leji.json MUST existir en la raíz del repositorio y validar frente a su esquema. Es el único nombre de archivo fijo de Leji: el archivo que el utillaje busca de forma fiable.
2. Índice. Una capa de contexto que declare conformidad indexed o superior MUST llevar un índice del contexto generado, nunca mantenido a mano: el utillaje resuelve los archivos de índice de categoría (categories.<id>.indexes, según content-categories.md) a los documentos que enumeran y escribe una entrada por documento gobernado. Cada entrada lleva un id estable, una path, un title y un identificador de category. Un generador SHOULD emitir también la clase (kind) del documento (intent o record); es opcional en el esquema para que un índice escrito antes de que existieran las clases siga siendo válido, y un consumidor trata un valor ausente como intent. La entrada de un registro lleva además su date cuando el documento declara una date válida en el frontmatter; el generador toma las fechas únicamente del frontmatter, nunca de la prosa ni de convenciones de nombres de archivo. Un índice desactualizado (uno que ya no coincide con lo que resuelven los archivos de índice) MUST tratarse como un fallo de validación. Una anfitriona que declara federation.mounts lleva además, en ese mismo índice, un array mounts de primer nivel: un registro de enrutamiento por montaje (name, source, pin, trackingRef cuando se declara, owner, role cuando se declara, y los metadatos de enrutamiento categories / topics / requiredWhen). Son únicamente registros de enrutamiento; el utillaje MUST NOT copiar las entradas ni la prosa de una hermana al índice de la anfitriona, y un registro de montaje no lleva nada que la audiencia de la anfitriona no pueda ver (según distribution.md, Montajes restringidos).
3. Registro de cambios. Una capa de contexto que declare conformidad indexed o superior MUST llevar un registro de cambios legible por máquinas con los cambios de la capa de contexto. Las entradas llevan un id estable, una date en UTC, un type, un summary de una línea y las paths afectadas. El orden canónico es derivado, no posicional: el utillaje MUST ordenar las entradas por (date, id) ascendente, y la posición en el array no significa nada. Como el id es único dentro del registro de cambios (Identificadores), (date, id) es un orden total incluso cuando dos cambios comparten date. Las entradas supervivientes son inmutables: el utillaje MUST tratar la modificación de una entrada publicada como un fallo de validación allí donde pueda establecer el estado anterior, y reordenar el array no es una modificación. Establecer ese estado exige una base de comparación distinta; donde el utillaje de referencia solo dispone de la revisión actual, como en una copia ordinaria de integración continua, la modificación no le resulta visible y es la revisión del conjunto de cambios la que la detecta (véase conformance.md). El registro de cambios es una superficie de actualidad, no un archivo histórico: una capa de contexto longeva SHOULD compactarlo en vez de dejar que crezca sin límite, y MAY compactarlo en cualquier momento eliminando entradas por el extremo más antiguo de ese orden, siempre que el mismo conjunto de cambios anexe una entrada de tipo compaction cuyo campo compacted registre el recuento y el primer y el último id eliminados. Eliminar algo que no sean las entradas más antiguas, eliminar sin una entrada de compactación y compactar hasta dejar el archivo vacío son fallos de validación. La disciplina de solo anexión se indexa por conjunto según el id y se comprueba contra el estado previo confirmado, así que necesita git en el momento de escribir; el archivo en sí se mantiene libre de git para los consumidores, y el historial de git guarda el registro completo. Un conjunto de cambios que toca documentos gobernados (aquellos a los que resuelven los archivos de índice de categoría) MUST anexar una entrada cuyas paths cubran las rutas gobernadas que cambió, de modo que cada documento gobernado modificado quede bajo alguna entrada anexada: la disciplina de solo anexión mantiene inmutables las entradas publicadas, y esta regla de cobertura mantiene completo el registro. MAY existir junto a él un registro de cambios legible por personas; el registro JSON es el que lee el utillaje.
4. Artefactos con frontmatter. Los perfiles de agente y los registros de decisión son documentos markdown cuyo frontmatter YAML valida frente a sus esquemas. El cuerpo en prosa queda libre; el frontmatter es el contrato con la máquina. MUST NOT exigirse perfiles o decisiones en JSON puro: estos documentos los leen personas.
5. Identificadores. Todos los valores de id MUST ser estables una vez publicados: los renombrados y los movimientos actualizan la path, nunca el id. Los identificadores van en minúsculas, separados por guiones y son únicos dentro de su tipo de artefacto. El id de una entrada de índice generada se deriva en este orden de prioridad: el id del frontmatter del documento si lo declara; si no, el id que el índice almacenado ya lleve para esa misma ruta o, en un movimiento puro que preserva el contenido, para ese mismo contenido; si no, un slug del nombre de archivo, desambiguado frente a su directorio padre. Gana el primero que exista, de modo que un id publicado sobrevive a un renombrado o a un movimiento y solo un documento completamente nuevo acuña uno fresco. Un documento que pudiera moverse y editarse en un mismo conjunto de cambios SHOULD declarar un id en el frontmatter: solo el frontmatter fija el id a través de un cambio simultáneo de ruta y contenido (los mecanismos de reserva por ruta y por hash fallan ambos), y el utillaje avisa (id-vanished) cuando desaparece un id almacenado, de modo que se detectan las referencias colgantes que deja.
6. Marcas de tiempo. Los valores de date del registro de cambios son ISO 8601 en UTC: o bien una fecha de calendario YYYY-MM-DD (ordenada como el inicio de ese día, T00:00:00Z), o bien una marca de tiempo de segundos enteros terminada en Z (por ejemplo 2026-06-13T15:04:05Z). Las horas sin zona, los desplazamientos distintos de UTC y las fracciones de segundo no están permitidos: las fracciones de segundo romperían la garantía de que una ordenación lexicográfica de date es una ordenación cronológica, ya que …05.1Z se ordena antes que …05Z siendo posterior. Todo campo de fecha de todo artefacto tiene rango de calendario, así que un mes 13 o un día 99 es inválido. Las fechas de los demás artefactos siguen ISO 8601 y MAY ser solo de fecha. Las rutas son de estilo POSIX, relativas a la raíz del repositorio, sin ./ inicial.
7. Todo artefacto JSON salvo el manifiesto MUST declarar la línea de esquema contra la que se escribió (schemaVersion), según versioning.md; el manifiesto declara la línea de especificación a la que apunta con la clave autonombrada leji.
8. Las superficies derivadas heredan las restricciones de acceso. El índice, el registro de cambios, el visor generado y cualquier vista compilada o exportada construida a partir del contenido de la capa de contexto son superficies derivadas, igual que lo es la salida que un agente produce a partir de ese contenido. Una superficie derivada lleva las restricciones de acceso del contenido más restringido del que se nutre. Una superficie derivada MUST NOT escribirse ni copiarse a un lugar con una audiencia más amplia que la de ese contenido sin un paso explícito y revisado de expurgo del contenido restringido que produzca una superficie separada para esa audiencia, y un agente MUST NOT citar ni resumir contexto restringido en una superficie de audiencia más amplia o menos restringida (un pull request, un ticket, un chat, un mensaje de commit o una capa de contexto pública). El índice de una capa de contexto restringida puede ser tan sensible como su prosa: los títulos, las rutas y los resúmenes la describen. Esto es una restricción sobre las personas y los agentes que operan el utillaje, no una comprobación que el utillaje realice: Leji no define ningún modelo de audiencia que una herramienta pueda leer para calcular qué es «audiencia más amplia» (el acceso corresponde al sistema de control de versiones, según governance.md, Límite de acceso), de modo que el SDK de referencia no lo aplica y lo más que hace cualquier herramienta es avisar (la exportación del visor avisa de que se aloje en privado).

Enrutamiento por tarea#

El índice, las asignaciones de categoría y los registros de decisión existen para que un agente pueda cargar la porción de contexto que una tarea necesita en vez del árbol entero. Esta sección define, de forma normativa, cómo el alcance de una tarea selecciona esa porción. Es el único algoritmo de enrutamiento al que se refiere el resto de la especificación: la sección de carga del perfil de arranque (boot-profile.md) remite aquí al agente en lenguaje de tarea, el alcance de los registros de decisión (decisions.md) coincide con él, y la lectura federada (distribution.md) lo reutiliza para decidir qué hermanas toca una tarea. El enrutamiento lee contexto; no es un sobre de tarea ni un protocolo de ejecución, que quedan fuera de la 1.0 (véase README.md, Límite de extensión).

1. Entrada. El alcance de una tarea es el conjunto de rutas POSIX relativas a la raíz del repositorio que la tarea lee o cambia (normalizadas según el requisito 6: estilo POSIX, relativas a la raíz, sin ./ inicial), junto con las categorías que la tarea nombre explícitamente y los temas que la tarea nombre explícitamente. Los temas son entradas explícitas: el algoritmo nunca los deriva de rutas, categorías, prosa o contenido. Cómo deriva un agente o una herramienta el alcance a partir de la tarea queda fuera del alcance normativo; la comparación que sigue, no.
2. Coincidencia de rutas (léxica, bidireccional). Una ruta declarada y una ruta de tarea coinciden cuando, tras la normalización (estilo POSIX, relativa a la raíz, sin ./ inicial, eliminada cualquier / final), las dos cadenas son iguales, o una es prefijo ancestro de la otra: la más corta es igual a la más larga truncada en un límite /. La comparación es puramente léxica: nunca consulta el sistema de archivos y no distingue entre una ruta que nombra un archivo y una que nombra un directorio, porque tras la normalización ambas son indistinguibles. Es contención en cualquiera de las dos direcciones (la relación underPath que comparten las implementaciones de referencia), de modo que una tarea de alcance amplio y un selector declarado de forma estrecha se encuentran sea cual sea el lado más amplio.
3. Coincidencia de categorías (estrecha), y los dos conjuntos de categorías. Las categorías de una tarea se dividen en expandidas y señalizadas. Una categoría que la tarea nombra explícitamente entra en ambos conjuntos. Una ruta de tarea que es en sí misma un documento gobernado (que coincide con su entrada de índice generada por igualdad exacta, nunca por contención) aporta la categoría de esa entrada únicamente al conjunto señalizado. Las categorías expandidas cargan sus documentos de intención y sus registros candidatos; las categorías señalizadas son una señal de coincidencia para las decisiones y los montajes de federación y no cargan nada por sí mismas. Un selector de categoría MUST NOT inferir una categoría para un archivo cualquiera del repositorio, y una ruta de tarea que no sea en sí misma un documento gobernado, incluido cualquier directorio ancestro de uno, no aporta categoría alguna. El alcance por rutas llega a los archivos; la expansión por categoría no lo sigue.
4. Coincidencia de temas (exacta, solo montajes). Un tema es una cadena no vacía de valores escalares Unicode, comparada por su codificación UTF-8; un sustituto suelto no es un tema válido. Ambos lados están sujetos a esa regla: un tema de tarea o una entrada de topics de un montaje que no sea una cadena no vacía de valores escalares Unicode es un error de entrada, y una implementación MUST rechazarlo en vez de devolverlo como una no coincidencia silenciosa. Un tema de tarea coincide con un tema declarado cuando las dos cadenas decodificadas son exactamente iguales. Las implementaciones MUST NOT cambiar mayúsculas y minúsculas, normalizar Unicode, comparar según la configuración regional, recortar, tokenizar, buscar subcadenas ni hacer coincidencias aproximadas en ninguno de los dos lados, de modo que grafías canónicamente equivalentes que difieren en bytes no coinciden; esta regla de igualdad es independiente del orden por bytes de los resultados que se define más abajo. Los temas de tarea duplicados forman una sola señal, así que nombrar un tema dos veces coincide exactamente igual que nombrarlo una vez. Un montaje de federación coincide cuando cualquier tema de la tarea es igual a cualquier tema que el montaje declare. Una coincidencia por tema selecciona únicamente el montaje: MUST NOT entrar en los conjuntos de categorías expandidas o señalizadas, ni cargar ningún documento o registro, ni enrutar ninguna decisión, ni evaluar requiredWhen, ni hacer que un montaje sea requerido.
5. Filtro de estado. Solo se enruta como guía vigente un registro de decisión cuyo status es vinculante. accepted y deprecated son vinculantes; un registro deprecated es vinculante con una postura de desactualización, y un agente MUST tratarlo como guía en retirada más que como práctica vigente asentada. Un registro superseded MUST NOT ser vinculante salvo como historia y MUST llevar supersededBy; los registros proposed y rejected MUST NOT ser vinculantes. Un registro vinculante está vivo.
6. Decisiones sin alcance. Un registro de decisión vivo que no declara ni affectedPaths ni affectedCategories es de alcance organizativo: se enruta para toda tarea, sea cual sea su alcance. Las decisiones vivas con alcance se enrutan solo cuando la tarea coincide con ellas por ruta (2) o por categoría (3).
7. Alcance de rutas vacío, y alcance vacío. Cuando el conjunto de rutas de la tarea está vacío, la coincidencia de rutas no aporta nada y un agente MUST declarar que no se evaluó el enrutamiento por rutas; las categorías nombradas explícitamente se siguen honrando y siguen expandiendo, y los temas nombrados explícitamente se siguen comparando. Tanto las categorías nombradas como los temas nombrados cuentan como alcance no vacío. El alcance completo de la tarea está vacío solo cuando no nombra rutas, ni categorías, ni temas; entonces un agente enruta únicamente el contexto incondicional del perfil de arranque y del perfil de agente, más las decisiones vivas sin alcance de ámbito organizativo. Un agente MUST NOT presentar una carga no enrutada como si estuviera acotada.
8. Los registros se enrutan como candidatos. Una categoría expandida enruta sus documentos de intención como contexto requerido; los registros de esa categoría se devuelven aparte, cada uno con su clase y su fecha, como candidatos que el lector carga a criterio propio. Un registro pasa a ser requerido solo cuando las rutas de la tarea lo seleccionan directamente según el punto 2, cuando un agente o el perfil de arranque lo nombran, o cuando una persona lo pide; ser una coincidencia de categoría, o llevar la fecha más reciente, nunca hace que un registro sea requerido. Cuando un registro es a la vez candidato por categoría y seleccionado directamente por ruta, gana la selección directa y es requerido. El enrutamiento MUST NOT certificar ningún registro como «el último» o «el vigente»: la 1.0 no define identidad de serie de registros ni garantía de orden, así que los juicios de actualidad corresponden al lector, hechos contra las fechas que expone el índice. Los registros de decisión conservan su propio enrutamiento (puntos 5 y 6) y nunca se enrutan como registros genéricos. Nombrar un archivo de decisión como ruta de tarea no enruta esa decisión; lo hace el alcance que ella declara.
9. Cita. Un agente que carga registros de decisión enrutados MUST citar qué registros coincidentes cargó, para que un lector pueda ver qué guía aplicó el agente e inferir cuál no.

La porción enrutada es lo que un agente carga para una tarea. Es la unión de: el conjunto de carga incondicional del perfil de arranque y el requiredRead del perfil de agente activo, que el agente sostiene como su línea base con independencia de cualquier alcance; todo documento gobernado de intención de una categoría expandida; toda entrada gobernada que las rutas de la tarea seleccionen según el punto 2; todo registro seleccionado directamente por ruta según el punto 8; y toda decisión viva con la que la tarea coincida por ruta o por una categoría señalizada o expandida, más las decisiones vivas sin alcance de ámbito organizativo.

Las categorías señalizadas aportan únicamente coincidencia, a las decisiones y a los montajes de federación, y nunca expanden un corpus.

La porción no es el sobre. Una herramienta que calcula el enrutamiento devuelve la porción junto a material que el agente no debe cargar sin que se le pida: los registros candidatos y los metadatos de candidatura que los rodean. Cargar el sobre entero desbarata el propósito del enrutamiento.

El orden de los resultados es normativo allí donde una herramienta emita uno, de modo que implementaciones independientes coincidan byte a byte: las categorías, en el orden canónico de categorías de esta especificación; los documentos, registros y decisiones, por ruta ascendente; los montajes, por nombre ascendente. La comparación de cadenas es por bytes sobre UTF-8, no dependiente de la configuración regional ni de la ordenación por puntos de código.

El utillaje MAY ofrecer un ayudante que calcule esta porción a partir de un conjunto de rutas; las implementaciones de referencia exponen uno (route). Ese ayudante calcula la parte dependiente del alcance y no está obligado a emitir la línea base, que quien lo invoca ya sostiene; la obligación del agente de cargar esa línea base no cambia. El enrutamiento es conforme siempre que un lector sin utillaje siga este algoritmo.

Notas (no normativo)#

El utillaje de referencia comprueba hoy el esquema del registro de cambios y su disciplina de solo anexión (leji validate ejecuta ambas); verificar la cobertura del registro de cambios contra una revisión base, es decir que toda ruta gobernada modificada aparezca en una entrada anexada, es una comprobación con informe que está en la hoja de ruta, todavía no una comprobación cuyo fallo impida continuar. Hasta que llegue, la cobertura se apoya en la disciplina de revisión y de integración continua atestiguada por proceso (véase conformance.md).

El índice es la fuente de navegación del contexto gobernado: leji viewer construye esa estructura gobernada a partir del índice y muestra debajo el árbol de directorios del repositorio como zona de referencia navegable. Así, una sola vista reúne el contexto gobernado y la navegación que el equipo ya utiliza. Cualquier herramienta de documentación puede proyectar el índice del mismo modo. La presentación no es normativa. La superficie es deliberadamente pequeña. Bastan cinco formas para que el utillaje valide una capa de contexto, la compare, puntúe su vigencia y encamine a un agente hacia la porción correcta; son lo bastante pocas como para que un equipo pueda tener presente toda la superficie. Todo lo que exceda esas cinco formas queda para después de la versión 1.0 y dependerá de la experiencia práctica.

pull request

Decisiones

Los registros de decisión recogen, con fecha, el porqué de la capa de contexto: decisiones de arquitectura, selección de proveedores, límites de alcance y decisiones deliberadas de no actuar. Evitan reabrir debates ya resueltos y proporcionan a los agentes el razonamiento, no solo la regla.

Los registros de decisión son el subtipo formal de registro (véase content-categories.md, Intención y registros): son registros por naturaleza, con un esquema y un ciclo de vida uniformes que los registros genéricos no tienen. Sus entradas de índice generadas llevan kind: record; un registro de decisión no declara clave kind propia (el esquema es cerrado, así que un kind explícito falla la validación).

Requisitos#

1. Los registros de decisión son markdown con frontmatter YAML válido frente a decision-record.schema.json, un registro por archivo. El corpus de decisiones es la unión de dos superficies declaradas en el manifiesto, y una capa de contexto MAY usar cualquiera de las dos o ambas: la ruta de registros declarada (machine.decisionRecordsPath, por defecto <root>/decisions/) y las entradas a las que resuelven los archivos de índice de la categoría decisions. Un registro MUST ser alcanzable a través de al menos una de las dos.
2. El frontmatter MUST llevar: id (estable), title, status y date. status es uno de proposed, accepted, superseded, deprecated o rejected.
3. El cuerpo MUST enunciar, en prosa: el contexto (qué situación obligó a decidir), la decisión en sí y sus consecuencias. Los encabezados de sección RECOMMENDED son ## Context, ## Decision y ## Consequences; un registro MAY añadir ## Alternatives.
4. Los registros son historia de solo anexión: un registro MUST NOT editarse para convertirlo en una decisión distinta. Dos campos del frontmatter son mutables a medida que una decisión envejece, status (su ciclo de vida) y supersededBy (que se fija cuando queda sustituida); todo lo demás, el id, el title y la date originales, el alcance declarado y el cuerpo en prosa, es inmutable una vez publicado. Una reversión o un cambio es un registro nuevo cuyo frontmatter fija supersedes, y el status del registro antiguo pasa a superseded con supersededBy fijado. El enlace de sustitución MUST mantenerse consistente en ambas direcciones: cuando el registro B fija supersedes: A, el registro A lleva status: superseded y supersededBy: B, y un registro superseded MUST nombrar a su sucesor en supersededBy. Ambos registros permanecen. El utillaje de referencia comprueba hoy la consistencia bidireccional de la sustitución. Todavía no verifica la inmutabilidad en sí (que los campos congelados y el cuerpo de un registro publicado no hayan cambiado frente a una revisión base); eso es una comprobación con informe que está en la hoja de ruta, todavía no una comprobación cuyo fallo impida continuar. Hasta que llegue, la inmutabilidad se apoya en la disciplina de revisión atestiguada por proceso (véase conformance.md).
5. Un registro MAY declarar affectedPaths y affectedCategories, para que el utillaje pueda encaminar desde el alcance de una tarea hacia las decisiones que la gobiernan. Cómo selecciona registros el alcance de una tarea (contención de rutas consciente del solapamiento, coincidencia estrecha de categoría, la vinculación de accepted / deprecated y el tratamiento de ámbito organizativo de un registro que no declara ninguno de los dos) es el algoritmo de enrutamiento por tarea de machine-readable-surface.md.
6. Las propuestas rechazadas también son registros (status: rejected). Una decisión que no se tomó, puesta por escrito, es el seguro más barato que hay contra volver a litigarla.

Compatibilidad con ADR (no normativo)#

Los registros de decisión de Leji se han diseñado para ser compatibles con los Architecture Decision Records: un directorio de ADR existente satisface decisions si se añaden los campos de frontmatter a cada registro (o a los nuevos a partir de ese momento) y se asigna el directorio en el manifiesto. No se exige ninguna herramienta de ADR ni se excluye ninguna.

pull request

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#

1. 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).
2. 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).
3. 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#

4. 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.
5. 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.
6. 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.
7. 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.
8. 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.
9. 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.

10. 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.
11. 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.
12. 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.
13. 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.

pull request

Distribución

Esta sección establece dónde reside la capa de contexto respecto al trabajo que describe. Hay tres patrones y una regla común a todos: la capa de contexto es solo documentación y MUST NOT introducir ninguna dependencia de compilación o de ejecución en ningún repositorio que la consuma.

Patrón 1: monorepo (por defecto)#

La capa de contexto vive en el mismo repositorio que el código y la infraestructura que describe, en la raíz del contexto. Este es el patrón RECOMMENDED siempre que el trabajo del equipo viva en un solo repositorio: el código, la infraestructura y el contexto se versionan juntos, y la desviación es estructuralmente difícil.

Patrón 2: el submódulo de solo documentación para escenarios multirepo#

Cuando el trabajo abarca muchos repositorios, la capa de contexto vive en un repositorio de contexto dedicado, y los repositorios que la consumen la montan como submódulo de git.

1. El repositorio de contexto es un repositorio git normal con su propio leji.json, sus políticas de rama y su proceso de revisión y aprobación.
2. Los repositorios consumidores MUST montarlo en una ruta fija (RECOMMENDED: context/) y MUST NOT acoplar ningún paso de compilación o ejecución a su presencia: un montaje ausente o desactualizado degrada el conocimiento, nunca la compilación.
3. Cada repositorio consumidor fija una versión concreta de la capa de contexto. Las actualizaciones de la fijación MUST llegar como conjuntos de cambios revisables (pull requests generados por script o abiertos por un bot), de modo que los cambios de contexto sean visibles, revisables y atribuibles repositorio a repositorio.
4. El utillaje SHOULD informar de las fijaciones desactualizadas (cuánto se ha quedado atrás cada repositorio consumidor respecto a la capa de contexto). El informe de fijaciones desactualizadas MUST preceder a cualquier comprobación que impida continuar: primero visibilidad, después controles obligatorios. El informe de fijaciones del SDK de referencia 1.0 cubre los montajes de federación (patrón 3); para las fijaciones del lado del consumidor de este patrón no incluye comprobación alguna, así que en federated este punto se atestigua por proceso (véase conformance.md); un equipo o su propio utillaje lo informa hasta que llegue una comprobación de referencia.

Patrón 3: federación de capas de contexto hermanas#

Los patrones 1 y 2 tienen cada uno una única capa de contexto: un monorepo posee una, y una organización multirepo consume una. La federación es el patrón para una organización donde más de un equipo ya posee una capa de contexto propia, y el objetivo es hacerlas legibles entre sí sin que nadie renuncie al control.

La reacción habitual es fusionarlas: crear un repositorio de contexto que contenga el conocimiento de todos los equipos. No lo haga. Una capa de contexto se mantiene vigente porque sus responsables la leen en cada tarea y corrigen los errores en el mismo conjunto de cambios. Si traslada el contexto de producto al repositorio de plataforma, separará el contenido de producto de la responsabilidad sobre él; se deteriorará mientras todos dan por hecho que ahora corresponde a otro equipo. Centralizar el conocimiento vuelve a crear el cuello de botella que, en un principio, hizo que quedara atrapado en cabezas e hilos de chat.

La federación compone las capas de contexto en lugar de absorberlas. La capa de contexto de un equipo se une al grafo de otro equipo como hermana: montada, referenciada y leída, nunca copiada.

1. Una capa de contexto hermana se une como montaje fijado declarado en federation.mounts del manifiesto de la anfitriona: el name y el owner de la hermana, su localizador de repositorio source, y una pin que nombra el identificador de commit completo e inmutable de la revisión de la hermana que lee la anfitriona. La fijación es la versión de registro del montaje, guardada en el propio manifiesto para que las actualizaciones de fijación lleguen como conjuntos de cambios revisables: un montaje registra qué versión de la verdad de otro equipo estaba leyendo este repositorio, no una bifurcación de ella. Un montaje MAY declarar trackingRef, una rama o etiqueta completamente cualificada del origen contra la que se juzga si está desactualizada y si es alcanzable; si falta, se usa la rama por defecto que anuncia el origen en el momento de la comprobación y se nombra en el informe.

2. La hermana conserva todo lo que la mantiene viva: su propio repositorio, responsable, proceso de revisión y aprobación, registro de cambios y declaración de conformidad. La anfitriona MUST NOT copiar contenido de la hermana dentro de sí misma. El contenido separado del equipo que lo posee se queda obsoleto sin que nadie responda, que es exactamente el fallo que la federación existe para evitar.

3. El contenido montado se materializa como una proyección de la capa hidratada por el resolutor, nunca como una copia confirmada. Una hermana suele ser una capa embebida en un repositorio mayor (patrón 1), así que extraer la hermana entera equivaldría a incorporar un producto completo para leer su contexto. En vez de eso, el utillaje extrae la proyección de la capa en la fijación, la unión deduplicada de todo lo que el propio manifiesto de la hermana hace legible (el leji.json de la raíz, el árbol bajo la raíz del contexto declarada, el perfil de arranque, los archivos de índice y registro de cambios para máquinas cuando existen en la fijación, los árboles de perfiles de agente y de registros de decisión cuando existen, todo perfil de agente nombrado por las vinculaciones de agents, todo archivo de índice de categoría y toda ruta gobernada que enumere el índice de contexto generado y fijado, estén donde estén; el manifiesto de la propia hermana define su proyección, la anfitriona nunca la cura), a una caché efímera que el control de versiones de la anfitriona ignora. El límite de fallo sigue esa misma línea: un archivo referenciado o exigido por esquema ausente en la fijación (el perfil de arranque, un índice de categoría, un perfil de agente vinculado, una ruta gobernada indexada) hace fallar la proyección con un código estable que nombra el artefacto que lo declara y la ruta ausente, mientras que un directorio ausente o un artefacto de máquina ausente no aporta nada y no hace fallar nada, tanto si su ubicación efectiva estaba declarada como si venía por defecto; git no puede representar un directorio vacío, y una capa sin índice generado sencillamente no tiene cierre de contenido más allá de su árbol raíz. Un fallo de proyección de clase disponibilidad (el contenido de la fijación falta o está mal formado) deja el montaje no disponible en esta máquina y nunca hace fallar la validación ordinaria de la anfitriona ni la compilación de su producto. Un fallo de proyección de seguridad o interno (una ruta que se escapa, una cadena mal formada, un límite excedido) aborta la hidratación con salida distinta de cero, y nunca se publica una proyección parcial. Los bytes fijados se resuelven desde un almacén de objetos git (un repositorio de pista local a la máquina, el almacén gestionado por el resolutor o la base de datos de objetos de un submódulo de la anfitriona), nunca desde un árbol de trabajo, y el acceso a la red ocurre solo como un paso explícito y consentido. Un repositorio anfitrión MAY llevar un submódulo de la hermana por sus propios motivos; el utillaje lo trata solo como un almacén de objetos local más, y una copia de trabajo nunca es contenido montado legible. Confirmar contenido de la hermana dentro de la anfitriona, incluido el contenido de la caché, no es conforme. La regla de solo documentación del patrón 2 se cumple por construcción: nada en la anfitriona se compila ni se ejecuta contra la proyección.

   Una ruta de machine que resuelve a la raíz del repositorio no selecciona nada. Un machine.agentProfilesPath o machine.decisionRecordsPath declarado que resuelva a la raíz del repositorio de la hermana no aporta ninguna selección de directorio a la proyección: honrarlo incorporaría el repositorio hermano entero, que es justo el resultado que la proyección de la capa existe para evitar. No se pierde nada de lo referenciado, porque los perfiles y los registros de decisión nombrados individualmente, a través de las vinculaciones de agents o del índice generado y fijado, siguen viajando; solo se descarta la selección general de la raíz.

   Límites de la proyección. Un resolutor MUST hacer cumplir cuatro límites, de modo que una implementación independiente rechace las mismas entradas en vez de que cada una elija su propio techo. Una proyección lleva como máximo 65.536 entradas, contadas tras la deduplicación. Su contenido suma como máximo 2 GiB (2.147.483.648 bytes). Ninguna ruta proyectada supera los 4.096 bytes, medidos como la codificación UTF-8 de la ruta y no como sus caracteres, puntos de código o unidades de cadena nativas de cualquier entorno de ejecución, que difieren entre implementaciones y aceptarían rutas distintas. Un listado completo de árbol ocupa como máximo 256 MiB (268.435.456 bytes) en transporte; esto acota los metadatos de enumeración que un resolutor lee para poder seleccionar, no el contenido proyectado que acota el límite de bytes, y los dos son deliberadamente cifras distintas porque un repositorio grande puede guardar una proyección válida perfectamente pequeña. Superar cualquiera de los cuatro es un fallo de proyección de clase seguridad.

4. Un montaje que no está materializado degrada el conocimiento, nunca la compilación. La validación separa tres cuestiones. Un manifiesto que miente es un error: nombres de montaje duplicados, un montaje que reutiliza el name de la propia anfitriona, o un source o pin ausente o mal formado. Un montaje declarado que sencillamente no está hidratado en esta máquina es un aviso: disponibilidad degradada honesta, informada y omitida. La integridad de una proyección materializada frente a su fijación es un diagnóstico que expone el utillaje, fatal solo bajo aplicación voluntaria. La validación ordinaria MUST NOT fallar, descargar ni preguntar porque un montaje no esté disponible; las anfitrionas que quieren aplicación se acogen a ella explícitamente (una comprobación de salud de la federación MAY hidratar y exigir después disponibilidad), y las obligaciones de un lector ante un montaje requerido por la tarea que no está disponible son la regla de fallar en cerrado que aparece más abajo.

5. Montar habilita la lectura, no la autoridad, y no concede acceso. Una anfitriona que monta a una hermana encamina hacia ella a lectores y agentes cuando estos ya tienen acceso a ella; montar ni concede ese acceso ni aprueba los cambios de la hermana. Las escrituras de cada capa de contexto las sigue aprobando su propio responsable, y quién puede leerla lo sigue decidiendo el sistema de control de versiones. La federación compone contexto legible para los participantes que los repositorios pertinentes ya admiten; deja quién aprueba, y quién puede leer, exactamente donde estaban.

6. Los montajes son directos y planos. Una anfitriona compone las hermanas que nombra; el utillaje MUST NOT descender recursivamente a los montajes de una hermana, y el contexto transitivo es solo para visualización: los montajes que declara una hermana nunca se resuelven, indexan ni enrutan sin una fijación directa en la anfitriona. El name de cada montaje MUST ser único dentro del manifiesto de la anfitriona y MUST NOT reutilizar el name de la propia capa de contexto anfitriona. Como nada atraviesa más allá de las hermanas declaradas de una capa de contexto, los rombos y los ciclos son inertes: que A monte a B y a C mientras B monta también a C son tres relaciones directas, no un grafo que recorrer.

Las capas de contexto montadas son fuentes distintas y con nombre, no fundidas en las categorías de la anfitriona. La capa de contexto propia de la anfitriona es la autoridad para el repositorio de la anfitriona; cada hermana es la autoridad para el suyo. No hay un espacio de nombres de toda la organización, y por tanto no hay precedencia entre hermanas que resolver: un agente carga la porción que necesita de la capa de contexto que la posee, nombrándola. Y el contenido montado es entrada no confiable: contexto legible, nunca instrucción ejecutable. La prosa de una hermana puede llevar errores o instrucciones inyectadas como cualquier otra superficie de lectura, así que un agente la trata como material que sopesar y citar, aplica la postura propia de la anfitriona a sus propias acciones, y nunca obedece texto imperativo hallado en un montaje como si fueran las instrucciones de la anfitriona.

El informe de fijaciones desactualizadas es consciente de la ascendencia y honesto sobre lo que pudo ver: el utillaje compara la fijación con la referencia testigo (trackingRef, o la rama por defecto que anuncia el origen) e informa de al día, atrasada en N, adelantada, divergente o sin relación, nombrando siempre la referencia comparada, la categoría de repositorio en la que se ejecutó la comparación (el almacén gestionado por el resolutor, una pista local a la máquina o un submódulo de la anfitriona), si el testigo era la referencia propia del resolutor o una que no le pertenece, la hora de observación y si la ascendencia estaba completa. Cuando no hay almacén de objetos alcanzable, el informe es unknown, nunca una suposición. Una fijación resoluble solo a través de una pista local a la máquina establece disponibilidad, no conformidad: en federated, la fijación MUST ser alcanzable desde una referencia anunciada de source (véase conformance.md), y una comprobación que no pueda alcanzar el origen informa unknown, que nunca otorga el nivel.

Una capa de contexto alcanza la conformidad federated solo cuando estas relaciones son reales y comprobables: la capa de contexto es consumida por al menos otro repositorio como montaje fijado, hay informe de fijaciones desactualizadas en funcionamiento, y todo montaje declarado lleva una declaración fijada completa (origen, fijación de commit completa, metadatos de enrutamiento) con la responsabilidad intacta (véase conformance.md). El SDK de referencia comprueba las partes mecánicas e informa de los problemas; el estado de materialización deliberadamente no es una entrada de conformidad, porque la disponibilidad en una máquina no dice nada sobre la veracidad de la declaración.

Hay un manifiesto completo para esta forma en examples/multi-repo/.

El círculo compone la responsabilidad; no la centraliza. Un monorepo es el círculo de personas y agentes de un equipo leyendo una capa de contexto; una organización multirepo es un círculo de esos círculos, cada uno todavía en manos de las personas que lo mantienen cierto.

Lectura de una capa de contexto federada#

Hacer legible el descubrimiento es tarea de la anfitriona, no del agente inferirlo. Una anfitriona que declara montajes los expone en los dos sitios que un agente ya lee: el perfil de arranque nombra a sus hermanas en lenguaje de tarea (según boot-profile.md), y el índice de contexto generado lleva un array de enrutamiento mounts (según machine-readable-surface.md). Un agente nunca tiene que leer el manifiesto para encontrar una hermana.

Al leer una anfitriona federada, un agente:

1. Carga primero el perfil de arranque de la anfitriona y su superficie legible por máquinas; la capa de contexto propia de la anfitriona es la autoridad para el repositorio de la anfitriona.
2. Lee los registros de enrutamiento de montajes visibles en la anfitriona antes de fijar el alcance de contexto de la tarea. Un montaje es requerido por la tarea cuando el perfil de arranque de la anfitriona, un registro de montaje del índice o los metadatos requiredWhen del montaje dicen que la tarea lo requiere; un montaje es relevante para la tarea cuando, bajo el algoritmo de enrutamiento por tarea (machine-readable-surface.md), al menos una de sus categories coincide con una categoría señalizada de la tarea, o al menos uno de sus topics coincide exactamente con un tema que la tarea nombra explícitamente. Una coincidencia por tema selecciona únicamente el montaje: no expande una categoría y no selecciona contenido alguno dentro de la hermana. Ese mismo algoritmo enruta después la porción que el agente carga del propio índice de la hermana.
3. Para cargar una hermana relevante para la tarea, obtiene la ubicación de la proyección hidratada del estado del resolutor (el mounts locate del SDK de referencia; nunca infiriendo rutas de caché), lee allí el leji.json de la hermana, verifica que el name de la hermana coincide con la declaración de la anfitriona, lee el perfil de arranque de la hermana y carga después solo la porción que la tarea necesita del propio índice de la hermana. Los hechos, las restricciones y las citas llevan el nombre de la capa de contexto de la que salieron, y el contenido montado sigue siendo entrada no confiable según las reglas de este patrón.
4. MUST NOT descender recursivamente a los federation.mounts de una hermana. Si una capa de contexto nieta hace verdadera falta para las tareas de la anfitriona, la anfitriona MUST declararla como montaje directo propio.
5. Aplica la postura según la responsabilidad: la postura de la anfitriona gobierna el trabajo en el repositorio de la anfitriona, y la postura de una hermana gobierna la interpretación de su contenido y los cambios que se le propongan. Donde la guía de la anfitriona y la de la hermana entren en conflicto para una misma tarea y no haya una única capa de contexto propietaria clara, el agente MUST detenerse y preguntar en vez de elegir una precedencia no enunciada.

El utillaje MAY ofrecer ayudantes de carga conscientes de los montajes, pero leer hermanas no exige utillaje Leji: las lecturas de repositorio en crudo son conformes cuando siguen este procedimiento y preservan los límites de acceso.

Montajes restringidos#

La federación cruza un límite de acceso cuando las capas compuestas tienen audiencias distintas (véase governance.md). El acceso lo sigue haciendo cumplir el sistema de control de versiones: un lector o puede resolver el repositorio de un montaje o no puede. La tarea de la especificación es evitar que ese límite se filtre y que falle en silencio.

1. Una capa restringida MUST NOT declararse como montaje en una anfitriona cuya audiencia sea más amplia que la de la propia capa restringida: todo participante que la anfitriona admite debe estar ya admitido en la capa montada. La propia declaración del montaje (su presencia, name, owner, role, categories, topics, requiredWhen, source, pin y trackingRef) MUST NOT revelar nada que la audiencia de la anfitriona no pueda ver. Donde una audiencia más amplia necesite una decisión restringida, publique una capa acompañante expurgada del contenido restringido, o un resumen público de la decisión, no un montaje a la capa restringida.

2. Un montaje es una referencia, no una concesión de acceso. Declarar un montaje nunca amplía quién puede leer la capa montada más allá de lo que el sistema de control de versiones ya permite; si un lector concreto puede resolverlo se decide allí, no en el manifiesto de la anfitriona.

3. Falle en cerrado, nunca en silencio. Un lector que no puede resolver un montaje requerido por la tarea (tal como se define en Lectura de una capa de contexto federada) MUST detenerse e informar de contexto incompleto. MUST NOT seguir adelante como si la capa inaccesible no existiera: un agente que actúa sobre contexto parcial que no puede ver es el fallo que esta regla existe para evitar. Lo recíproco también es un fallo: un lector que sí puede resolver una hermana requerida o relevante para la tarea pero la omite igualmente está actuando sobre contexto silenciosamente incompleto y no es conforme.

   Qué puede y qué no puede respaldar aquí el utillaje: un validador informa de la disponibilidad local (un montaje declarado sin proyección hidratada aquí), y el algoritmo de enrutamiento decide la relevancia para la tarea por solapamiento de categorías y temas (los SDK de referencia exponen los montajes relevantes para la tarea; véase machine-readable-surface.md, Enrutamiento por tarea). Pero que algo sea requerido por la tarea depende de requiredWhen, que son condiciones de tarea en texto libre, y la alcanzabilidad en ejecución depende del acceso propio del lector en el momento de leer; ambas corresponden al criterio del agente, no de una herramienta. El MUST de fallar en cerrado lo atestigua, por tanto, el agente: el utillaje expone lo que puede ver, el agente hace cumplir la parada.

Notas (no normativo)#

La mala fama de los submódulos procede de los submódulos de código acoplados a la compilación. Una variante dedicada exclusivamente a documentación no presenta ninguno de esos modos de fallo: nada compila contra ella, nada se rompe si queda desactualizada y la fijación se limita a registrar «con qué versión de la verdad trabajaba este repositorio». Es información, no riesgo.

La federación parece más piezas móviles que una fusión, y es menos. Una fusión es barata una vez y cara para siempre: cada edición entre equipos pasa desde entonces por quien posee el repositorio central, y las partes que ningún equipo lee a diario son las que se pudren. Los montajes hermanos mantienen cada capa de contexto pequeña, con responsable y leída, y solo pagan el precio de una actualización de fijación, que es un diff revisable, no una reunión.

pull request

Conformidad

La adopción parcial es intencionada. Hay cuatro niveles, cada uno incluido en el siguiente, y el equipo declara el suyo en el manifiesto (conformance.claimedLevel). La conformidad es exclusivamente autodeclarada: no existe ningún programa de certificación.

La conformidad se evalúa contra la capa de contexto tal como está materializada allí donde se ejecuta la comprobación, no contra una capa canónica que una copia pudiera representar. Una copia alcanzada sin su repositorio se lee en el modo degradado de context-layer.md, y la lectura degradada nunca es una vía hacia la autoridad canónica: una copia así no verifica, y el utillaje lo dice en vez de dejar la cuestión abierta.

La mayoría de los puntos de la lista están verificados por máquina: el utillaje de referencia los comprueba frente a la capa y hace fallar cualquier declaración que no se sostenga. Se informan cuatro resultados que, deliberadamente, no son intercambiables:

• fail: se reunió la evidencia y el requisito no se cumple.
• (atestiguado por proceso), informado como manual: el punto describe una práctica del equipo (un proceso de revisión y aprobación, un trabajo de integración continua, un consumidor externo) que ninguna herramienta puede confirmar solo desde el repositorio, así que el equipo responde por ella. Solo los puntos etiquetados abajo como (atestiguado por proceso) se informan alguna vez de este modo.
• unknown: un punto de máquina cuya evidencia no se pudo obtener en esta ejecución, como la comprobación federada de alcanzabilidad de la fijación sin acceso al origen, o la disciplina de solo anexión sin una base git con la que comparar. unknown nunca otorga un nivel, y nunca refuta una declaración que una ejecución con evidencia podría confirmar.
• not applicable: un punto de máquina condicional que no aplica a esta capa, como los puntos federados de montajes en una capa que no declara ninguno. No se puntúa, y no es evidencia en ninguna dirección.

El verifiedLevel que informa el utillaje es el nivel más alto cuyos puntos aplicables verificados por máquina pasan todos, y nunca por encima del nivel que la capa declara; tanto fail como unknown impiden la concesión, y los puntos atestiguados por proceso o no aplicables no se puntúan. El tope sobre la declaración es deliberado: la verificación responde a si la declaración se sostiene, no a qué podría declarar la capa, de modo que una capa que declara core y cuya evidencia la llevaría a governed sigue informando core, y la forma de elevar el nivel informado es elevar la declaración. verifiedLevel nunca afirma los puntos atestiguados por proceso, así que un verifiedLevel que pasa es necesario pero no suficiente para un nivel que los lleva. Cada punto de abajo está verificado por máquina salvo que esté etiquetado como (atestiguado por proceso).

Dos puntos verificados por máquina se comportan de forma distinta en una copia degradada, y la diferencia se sigue de la evidencia que tiene cada uno. La presencia de git queda respondida: una copia que no está en un repositorio git no cumple el requisito de core de que la capa de contexto viva en uno, así que el punto es fail. La disciplina de solo anexión del registro de cambios no queda respondida: el archivo puede estar perfectamente bien formado mientras el estado previo confirmado con el que compararlo es inalcanzable, así que el punto es unknown y la capa sencillamente no verifica en indexed desde esa copia. Ninguno se informa como manual, que queda reservado a los puntos etiquetados como atestiguados por proceso. Aparte de eso, la regla de vigencia del lector (exponer el contexto cargado desactualizado, y detenerse o preguntar ante un elemento requerido caducado, según governance.md) regula el comportamiento del lector; no es una comprobación que determine la conformidad: el leji route de referencia estampa cada documento enrutado con su horizonte de revisión y su caducidad para que un agente pueda aplicarla.

Tres puntos se verifican hoy con menos profundidad de la que declara su intención, y la brecha se nombra aquí en vez de dejar que un lector la descubra. El punto del perfil de arranque se verifica como presencia en la ruta declarada y como presencia de los encabezados de identidad, carga y postura (toda ejecución de validate informa de un encabezado ausente como un aviso boot-profile-sections que no impide continuar), y si la sección de Identidad dice algo sustancial pasa por el lint voluntario --content, que además señala el texto de marcador de posición en cualquier parte del perfil. El punto de la decisión real se verifica como frontmatter válido según el esquema en al menos un registro resuelto; la sustancia del cuerpo (una decisión de verdad, no un esbozo) también pasa por --content. El punto del registro de cambios es el tercero: la disciplina de solo anexión se comprueba contra el estado del archivo en HEAD, lo que detecta una reescritura que todavía esté en el árbol de trabajo, el caso para el que existe un hook de pre-commit. En una copia de integración continua el árbol de trabajo es HEAD, así que una reescritura que llega ya confirmada no le resulta visible a la comprobación, y es la revisión del conjunto de cambios la que lo cubre. El punto verifica, por tanto, el árbol de trabajo, no el historial. La intención enunciada en cada uno de los tres puntos sigue siendo normativa respecto a lo que lleva una capa de contexto conforme; profundizar las comprobaciones de máquina, y comparar el registro de cambios contra una revisión base explícita, están en la hoja de ruta del utillaje de referencia. La verificación de federated exige además al menos una entrada declarada en federation.mounts: una capa de contexto que solo provee (una que otros repositorios consumen pero que no declara montajes propios) verifica en governed, y su condición de federada descansa en los puntos de consumo atestiguados por proceso.

Nivel 1: core#

Existe una capa de contexto y tanto las personas como los agentes pueden trabajar a partir de ella.

• La capa de contexto vive en un repositorio git, versionada junto con el trabajo que describe (según context-layer.md, Requisitos).
• leji.json en la raíz del repositorio, válido frente al esquema del manifiesto.
• Un perfil de arranque en la ruta declarada, que cubra identidad, carga y postura.
• Al menos domain o system asignada (mediante sus archivos de índice) y poblada con al menos un documento de intención resuelto (los registros por sí solos no aportan contexto operativo), más decisions con al menos un registro de decisión real: un registro con un status concreto y una decisión de verdad en su cuerpo, no un esbozo vacío ni un marcador de posición.
• Un responsable principal con nombre.
• Los archivos de entrada de proveedor, si existen, redirigen al perfil de arranque.

Nivel 2: indexed#

La capa de contexto es legible para el utillaje.

• Todo lo de core.
• Un índice de contexto generado, al día con el árbol.
• Un registro de cambios legible por máquinas; los cambios de la capa de contexto anexan entradas.

Nivel 3: governed#

Los mecanismos de forzado son mecánicos, no de buena voluntad.

• Todo lo de indexed.
• Los cambios de la capa de contexto requieren la revisión y aprobación del repositorio; las personas los aprueban. (atestiguado por proceso)
• Perfiles de agente (al menos uno con role: core) válidos frente al esquema de perfiles.
• La integración continua valida la superficie: manifiesto, índice que coincide con el árbol, disciplina del registro de cambios, frontmatter de perfiles, rutas declaradas que resuelven. (atestiguado por proceso)
• Los horizontes de vigencia están declarados y comprobados (basta con que la comprobación solo informe).

Nivel 4: federated#

La capa de contexto abarca una organización multirepo.

• Todo lo de governed.
• La capa de contexto es consumida por al menos otro repositorio como montaje fijado, y las actualizaciones de fijación llegan como conjuntos de cambios revisables. (atestiguado por proceso)
• Hay informe de fijaciones desactualizadas en funcionamiento: los consumidores pueden ver cuánto se han quedado atrás sus fijaciones respecto a la referencia testigo. El informe consciente de la ascendencia del SDK de referencia cubre los montajes de federación declarados; el informe del lado del consumo más allá de eso corre a cargo del equipo. (atestiguado por proceso)
• Cualesquiera capas de contexto hermanas se declaran como montajes fijados completos según distribution.md: un source normalizado y una pin de commit completa, con la responsabilidad intacta. El estado de materialización en una máquina concreta no es una entrada de conformidad.
• La fijación de cada montaje declarado es alcanzable desde una referencia anunciada de su source (el trackingRef declarado, o la rama por defecto del origen). Esta comprobación necesita acceso al origen: sin él el resultado es unknown, y unknown nunca otorga el nivel. Una fijación resoluble solo a través de una pista local a la máquina es disponibilidad, no conformidad.
• Cada montaje declarado lleva metadatos de enrutamiento: al menos categories, más topics o requiredWhen, para que un agente pueda decidir la relevancia sin leer la hermana.
• El perfil de arranque expone todas las hermanas montadas, y el índice generado lleva el array de enrutamiento mounts, de modo que un agente descubre y carga hermanas sin leer el manifiesto (según boot-profile.md y machine-readable-surface.md).

Notas (no normativo)#

core es el mínimo que hace real una capa de contexto, indexed añade la superficie generada que lee el utillaje, governed es donde la capa de contexto deja de depender de la disciplina de nadie, y federated es para organizaciones donde más de un equipo ya posee una capa de contexto que merece la pena mantener entera. La mayoría de los equipos deberían llegar a governed y quedarse ahí; federated existe para esas organizaciones, no como insignia de madurez.

pull request

Versionado

La especificación, los esquemas y el utillaje que los implementa se versionan de forma independiente.

La especificación#

1. La especificación lleva una versión SemVer (actualmente 1.0.0). Los cambios incompatibles exigen una versión mayor; todo cambio se anota en el registro de cambios del repositorio.
2. Una capa de contexto declara la línea de especificación a la que apunta en leji.json mediante la clave autonombrada leji (por ejemplo "leji": "1.0"), siguiendo la convención de OpenAPI. El valor es la línea de la especificación (major.minor), nunca su versión de parche: una versión de parche (1.0.0 a 1.0.1) refina la redacción o el utillaje sin mover la línea, así que el manifiesto se queda en "1.0" a lo largo de cada parche. El utillaje MUST validar una capa de contexto contra la línea declarada, no contra la más nueva.

Líneas de vista previa#

Una línea de especificación MAY designarse como vista previa. Mientras esté en vista previa, puede revisarse sobre la marcha: MAY cambiar de formas que en otro caso serían incompatibles, en vez de subir a una versión nueva, hasta que se congela en la disponibilidad general (GA). La regla de que «los cambios incompatibles exigen una versión mayor» (punto 1) y la regla de que «el $id se mueve ante un cambio incompatible de forma» (punto 3) se aplican desde el congelado en GA en adelante, no mientras una línea está en vista previa. En GA la línea se congela y ambas reglas entran en vigor.

Una línea que se publica antes de la disponibilidad general MUST declararlo en su primera publicación.

La línea 1.0 está congelada en la versión v1.3.0 del utillaje de referencia. Dentro de la línea, los cambios de esquema son solo aditivos y el $id se queda en v1.0; cualquier cambio incompatible se publica como línea nueva, nunca sobre la marcha.

Los esquemas#

3. Cada esquema lleva un $id estable con la forma https://leji.org/schemas/v<major>.<minor>/<name>.schema.json. La línea del $id se mueve solo cuando la forma del esquema cambia de manera incompatible.
4. Dentro de una línea publicada, los cambios de esquema MUST ser aditivos (nuevos campos opcionales). Las eliminaciones de campos o los cambios semánticos exigen una línea nueva.
5. Los artefactos legibles por máquinas distintos del manifiesto declaran la línea de esquema contra la que se escribieron mediante schemaVersion; el manifiesto declara la línea de especificación a la que apunta mediante la clave autonombrada leji (punto 2).

Conjunto de estabilidad#

Lo siguiente queda congelado dentro de una línea de especificación; el utillaje (incluidas futuras implementaciones comerciales) se construye contra ello sin esquemas paralelos:

• la forma del manifiesto y su nombre de archivo fijo leji.json,
• los identificadores de categoría (domain, system, practice, governance, decisions),
• los identificadores de nivel de conformidad (core, indexed, governed, federated),
• las reglas de normalización de identificadores y rutas según machine-readable-surface.md,
• las formas de la entrada de índice, la entrada de registro de cambios, el perfil de agente y el registro de decisión.

Utillaje que la implementa (no normativo)#

Los SDK y las CLI se versionan con su propio SemVer y declaran qué líneas de especificación admiten. Los SDK de referencia de este repositorio son el paquete npm @leji-org/leji (packages/sdk), el paquete PyPI leji (packages/sdk-py) y el módulo Go leji (packages/sdk-go, un único binario estático); son idénticos en comportamiento y se prueban contra un mismo conjunto compartido de fixtures.