spec 1.0 · normativo

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.