spec 1.0 · normativo

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#

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.
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.
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.
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í.
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.
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.
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.

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.
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):

MUST NOT guardar contenido canónico de la capa de contexto.
Si existen, MUST redirigir al perfil de arranque (normalmente un puntero de una línea).
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.
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.