xonecode 0.38.44 → 0.39.4

package/dist/core/fuentes.d.ts

@@ -0,0 +1,96 @@
+import type { Agente } from "./agentes.js";
+/**
+ * Las reglas PURAS de traer una fuente de Google Fonts al proyecto: qué familia y peso valen,
+ * cómo se llama el fichero, de qué URLs se aceptan respuestas y qué bytes son un `.ttf`. La red
+ * es `FuentesPort` (`core/ports.ts`) y la hace `agent/config/fuentesEnRed.ts`; las tools son
+ * `agent/grafo/fuentesDeGoogle.ts`.
+ *
+ * ## Lo medido contra la red, sin clave
+ *
+ * - El CATÁLOGO es `fonts.google.com/metadata/fonts`: un JSON de unos 2,7 MB con ~1.950
+ *   familias, cada una con sus pesos como claves de `fonts` (`"400"`, `"700i"` es la cursiva).
+ * - El FICHERO sale de la API `css2`: pedida sin cabeceras de navegador moderno, su `@font-face`
+ *   apunta a un `.ttf` ESTÁTICO de ese peso en `fonts.gstatic.com` (`font/ttf`). Un peso que la
+ *   familia no tiene contesta 400. Estático y por peso es justo la convención de la skill
+ *   (`fontname: Roboto-Bold.ttf`); el `.ttf` variable del repo de GitHub sale con su peso por
+ *   omisión y su nombre no se deduce sin listar la carpeta.
+ * - Tamaños: Inter 700 son 326 KB; Noto Sans JP 400, 5,7 MB (de ahí el tope).
+ */
+export declare const NOMBRE_BUSCAR_FUENTE = "buscar_fuente";
+export declare const NOMBRE_TRAER_FUENTE = "traer_fuente";
+/** La carpeta de una app XOne de donde `fontname` toma el `.ttf`. */
+export declare const CARPETA_DE_FUENTES = "fonts";
+/**
+ * Quién las recibe: quien puede dejar el `.ttf` en `fonts/`. Sin `escribeEn` escribe el proyecto
+ * entero (el desarrollador); con él, solo si una de sus carpetas cubre `fonts/` (el diseñador, que
+ * hace los RECURSOS: una fuente lo es, como un icono). La forma de `recibeBuscarIcono`, con otra
+ * carpeta. Regla de DATO, no un nombre. Solo llega a `motor: "modelo"` (un externo no recibe tools
+ * propias), y eso lo comprueba quien monta.
+ */
+export declare function recibeFuentes(a: Pick<Agente, "soloLectura" | "ejecucion" | "escribeEn">): boolean;
+/** Tope de UNA llamada de red. El catálogo son 2,7 MB y una fuente CJK pasa de 5 MB. */
+export declare const TOPE_DE_FUENTES_MS = 30000;
+/** Lo que se acepta como `.ttf`. Medido: Noto Sans JP 400 son 5,7 MB; esto es holgura. */
+export declare const TOPE_DE_FUENTE_BYTES: number;
+/** Lo que se acepta como catálogo (2,7 MB medidos) o como hoja `css2` (unos cientos de bytes). */
+export declare const TOPE_DE_CATALOGO_BYTES: number;
+export declare const TOPE_DE_CSS_BYTES: number;
+export declare const LIMITES_DE_BUSQUEDA_DE_FUENTES: {
+    readonly porOmision: 8;
+    readonly maximo: 20;
+};
+/** Los hosts son CONSTANTES: uno distinto es una decisión, no un parámetro. */
+export declare const URL_DEL_CATALOGO = "https://fonts.google.com/metadata/fonts";
+export declare const BASE_DE_CSS = "https://fonts.googleapis.com/css2";
+export declare const HOST_DE_FICHEROS = "fonts.gstatic.com";
+/** Los pesos que se traen. El catálogo trae también 1 y 1000 en alguna familia variable: fuera. */
+export declare const PESOS: readonly [100, 200, 300, 400, 500, 600, 700, 800, 900];
+export type Peso = (typeof PESOS)[number];
+/** Una familia del catálogo, recortada a lo que el agente necesita. */
+export interface FamiliaDeFuente {
+    familia: string;
+    categoria: string;
+    /** Los estilos que hay, como el catálogo: `"400"`, `"700i"`. Solo los de `PESOS`. */
+    estilos: string[];
+}
+export declare function motivoDeFamiliaInaceptable(familia: string): string | undefined;
+export declare function motivoDePesoInaceptable(peso: number): string | undefined;
+/** La clave del catálogo para un peso y estilo: `700` → `"700"`, cursiva → `"700i"`. */
+export declare function claveDeEstilo(peso: Peso, cursiva: boolean): string;
+/**
+ * El nombre del fichero, por la convención de los estáticos de Google: la familia SIN espacios,
+ * un guion y el estilo (`Roboto Mono`, 700 cursiva → `RobotoMono-BoldItalic.ttf`; 400 cursiva →
+ * `RobotoMono-Italic.ttf`). Es también lo que va en `fontname`, a secas: XOne lo busca en `fonts/`.
+ * Medido sobre el catálogo: quitar los espacios no junta dos familias en un mismo nombre.
+ */
+export declare function nombreDeFicheroDeFuente(familia: string, peso: Peso, cursiva: boolean): string;
+/** Dónde se escribe (ruta virtual): `/fonts/Inter-Bold.ttf`. */
+export declare function rutaDeFuente(familia: string, peso: Peso, cursiva: boolean): string;
+/** La hoja `css2` de UN estilo. La familia ya viene validada: solo letras, cifras y espacios. */
+export declare function urlDeCss(familia: string, peso: Peso, cursiva: boolean): string;
+/**
+ * De la hoja `css2`, la URL del `.ttf`, o `undefined`. Solo si es HTTPS a `fonts.gstatic.com` y
+ * declara `truetype`: otro host u otro formato (un `woff2`, si Google cambiara lo que sirve a un
+ * cliente sin navegador) no es lo medido.
+ */
+export declare function urlDeTtfEnCss(css: string): string | undefined;
+/**
+ * ¿Son estos bytes un TrueType? Por su FIRMA, no por la cabecera HTTP: `00 01 00 00` (lo medido
+ * en todo lo que sirve gstatic) o `true` (el de Apple). Un OpenType con CFF (`OTTO`) no se acepta:
+ * lo que XOne dice cargar es `.ttf`.
+ */
+export declare function esTrueType(bytes: Uint8Array): boolean;
+/** Del catálogo, las familias con forma conocida. Lo que no encaja no es del contrato y se salta. */
+export declare function familiasDelCatalogo(cuerpo: unknown): Array<FamiliaDeFuente & {
+    popularidad: number;
+}>;
+/**
+ * Buscar en el catálogo: la coincidencia EXACTA primero (sin mayúsculas ni espacios: «robotomono»
+ * es «Roboto Mono», que es como lo escribe una maqueta en su `fontFamily`), luego las que la
+ * contienen, por popularidad (en el catálogo, menor es más popular).
+ */
+export declare function buscarEnCatalogo(catalogo: ReadonlyArray<FamiliaDeFuente & {
+    popularidad: number;
+}>, consulta: string, limite: number): FamiliaDeFuente[];
+/** Los estilos de una familia, legibles: `400, 700, 400 cursiva`. */
+export declare function estilosLegibles(estilos: readonly string[]): string;

package/dist/core/geometriaDePantalla.d.ts

@@ -0,0 +1,171 @@
+/**
+ * La GEOMETRÍA de una pantalla: comparar CAJAS, no píxeles. Pura.
+ *
+ * Existe por una sesión de MyAllXOne (crear una calculadora de Stitch): diez rondas de «cambio el CSS →
+ * despliega y captura → compara» porque nada le decía al agente QUÉ estaba mal. El comparador de franjas
+ * (`compararCapturas.ts`) da dónde hay contenido, no qué tecla; el SSIM se quedó en 0,44–0,48 en todas
+ * las rondas; y el crítico con visión no vio la «=» tapada por la barra de navegación y se inventó
+ * diferencias de color. Pero los dos lados se pueden tener como DATOS:
+ *
+ * - **El aparato** da su árbol de controles (`getAllElements`): cada control con su texto, su nombre y
+ *   su caja en píxeles. Lo guarda con la captura, en el mismo momento, `xone-captura-android`.
+ * - **Una maqueta de Stitch** trae `code.html`: renderizado, da la caja de cada botón con su texto.
+ *
+ * Dos niveles:
+ * 1. **Solo con el aparato** (`hallazgosDelAparato`), haya maqueta o no: lo TAPADO por las barras del
+ *    sistema (Android dibuja de borde a borde, así que un control puede quedar debajo de la de
+ *    navegación), lo que se SALE de la pantalla y lo que se SOLAPA.
+ * 2. **Con la maqueta** (`compararConMaqueta`): se EMPAREJAN por texto Y posición —por texto solo, el
+ *    «0» del visor se emparejó con la tecla «0»— y se dice qué FALTA, qué cambia de FILA o de ORDEN, y
+ *    qué TAMAÑO RELATIVO a sus vecinas cambia. Nada de coordenadas absolutas: las proporciones de la
+ *    maqueta (390×746) y del aparato (1080×2400) no coinciden, y cada «está 30 px más abajo» sería ruido.
+ *
+ * Lo que es BLOQUEANTE (tapado, fuera, falta) decide el veredicto; el resto son diferencias.
+ */
+export interface Caja {
+    x: number;
+    y: number;
+    ancho: number;
+    alto: number;
+}
+export interface Rectangulo {
+    izquierda: number;
+    arriba: number;
+    derecha: number;
+    abajo: number;
+}
+export interface ControlDelAparato {
+    nombre?: string;
+    texto?: string;
+    tipo?: string;
+    /** El `propType` de XOne: `B` botón, `IMG` imagen, `T`/`TL`/`L` texto o etiqueta… */
+    clase?: string;
+    caja: Caja;
+    /** El contenedor del que cuelga (un número por contenedor del árbol): solo los HERMANOS pueden solaparse por error. */
+    padre?: number;
+    /** El árbol dice que no se ve (`visibleBounds: null`): está fuera por el scroll de su lista, no fuera de la pantalla. */
+    fueraDeVista?: true;
+}
+export interface GeometriaDelAparato {
+    pantalla: {
+        ancho: number;
+        alto: number;
+    };
+    barras?: {
+        estado?: Rectangulo;
+        navegacion?: Rectangulo;
+    };
+    controles: ControlDelAparato[];
+}
+export interface ElementoDeMaqueta {
+    /** El texto visible. Un botón de solo icono trae el nombre de la ligadura (`backspace`): eso NO es texto. */
+    texto: string;
+    caja: Caja;
+    /** Su ancho no se conoce (una maqueta DESCRITA sin unidades): no entra en la comparación de anchos. */
+    sinAncho?: true;
+    /**
+     * Es un BOTÓN de la maqueta (`cajasDeMaqueta.ts#medirElementos`). Lo que no lo es y no tiene letras es un DATO de
+     * ejemplo («12 pend.», el reloj «09:41» de una barra de iOS simulada): que falte en el aparato no es un defecto.
+     */
+    boton?: true;
+    /** La caja de su TEXTO, si es un botón con el texto en un elemento propio: ahí se mide la letra; en `caja`, la forma. */
+    cajaDelTexto?: Caja;
+}
+export interface MaquetaMedida {
+    ancho: number;
+    alto: number;
+    elementos: ElementoDeMaqueta[];
+    /**
+     * Los BLOQUES anchos de la maqueta (cabecera, visor, panel…): casi tan anchos como la pantalla. No son controles,
+     * pero su fondo y su forma también son el diseño (medido: una cabecera amarilla que la maqueta no tiene no salía).
+     */
+    bloques?: Caja[];
+}
+export interface HallazgosDeGeometria {
+    /** Tapado, fuera de la pantalla, falta: deciden el veredicto. */
+    bloqueantes: string[];
+    /** Fila, orden, tamaño relativo, solapes, lo que sobra. */
+    diferencias: string[];
+    /** Lo que no se pudo comparar y por qué: se dice, no se calla. */
+    notas: string[];
+}
+/** Cuántos hallazgos de cada clase como mucho: más es ruido que nadie lee. */
+export declare const TOPE_DE_HALLAZGOS = 10;
+/** Los controles del árbol de `getAllElements` (lista anidada de nodos con `bounds`), aplanados. */
+export declare function controlesDelArbol(arbol: unknown): ControlDelAparato[];
+export declare function hallazgosDelAparato(g: GeometriaDelAparato): HallazgosDeGeometria;
+/**
+ * El texto con el que se empareja, o `""` si es un ICONO. Los botones de Stitch llevan iconos de Material
+ * como ligaduras (`backspace`, `content_copy COPY`): una palabra en minúsculas y con `_` es el nombre de un
+ * icono, no texto que se vea.
+ */
+export declare function textoParaEmparejar(texto: string): string;
+interface Pareja {
+    maqueta: ElementoDeMaqueta;
+    aparato: ControlDelAparato;
+    /** Tenía texto en la maqueta y se emparejó por POSICIÓN con un control sin texto (una imagen). */
+    porPosicion?: true;
+    /** Los dos tienen PALABRAS y dicen otra cosa, en el mismo sitio: un texto traducido o cambiado. */
+    otroTexto?: true;
+}
+/**
+ * ¿Lleva LETRAS el texto (ya pasado por `textoParaEmparejar`)? Una cifra o un signo no se empareja por sitio con una
+ * palabra: medido en la calculadora, el «19» del visor salía como pareja de «COPY».
+ */
+export declare function tieneLetras(texto: string): boolean;
+/** Lo que se VE de un texto: sin el nombre de la ligadura de un icono (`content_copy COPY` → `COPY`). */
+export declare function textoVisible(texto: string): string;
+/**
+ * Empareja uno a uno: primero por TEXTO igual, eligiendo entre los iguales el más cercano (así el «0» de
+ * la tecla no se empareja con el «0» del visor); después los ICONOS por posición, solo si el más cercano
+ * está cerca y libre. Lo que no se empareja se devuelve aparte.
+ */
+export declare function emparejar(m: MaquetaMedida, g: GeometriaDelAparato, 
+/** Solo por texto: con una maqueta DESCRITA las posiciones son de una rejilla, y un icono «cerca» no significa nada. */
+soloTexto?: boolean): {
+    parejas: Pareja[];
+    sinPareja: ElementoDeMaqueta[];
+};
+/** Agrupa en FILAS: dos van en la misma si sus centros verticales están a menos de medio alto. Devuelve el índice de fila de cada uno. */
+export declare function filas(cajas: readonly Caja[]): number[];
+/**
+ * Cómo se compara. Por omisión, una maqueta MEDIDA contra el aparato. `aproximada` es una maqueta DESCRITA
+ * por el modelo (`maquetaDescrita.ts`): sus cajas son una rejilla, así que se empareja solo por texto, no hay
+ * proporción que comparar, y lo que falta NO es bloqueante —es lo que el modelo dijo ver, no una medida—.
+ */
+export interface ModoDeComparacion {
+    aproximada?: true;
+    /** Cómo se nombra cada lado en los hallazgos: por omisión «la maqueta» y «el aparato». */
+    nombres?: {
+        maqueta: string;
+        aparato: string;
+    };
+}
+export declare function compararConMaqueta(m: MaquetaMedida, g: GeometriaDelAparato, modo?: ModoDeComparacion): HallazgosDeGeometria;
+/** Los dos niveles juntos, recortados al tope, y sin repetir. */
+export declare function hallazgosDeGeometria(g: GeometriaDelAparato, m?: MaquetaMedida): HallazgosDeGeometria;
+/**
+ * La marca de una línea BLOQUEANTE en el informe del crítico: la lee el cierre de una tarea (`bloqueantesDelInforme`) para
+ * su `## CRITICAL`, y le dice al agente qué es lo grave entre las diferencias.
+ */
+export declare const MARCA_DE_BLOQUEANTE = "BLOQUEANTE \u00B7 ";
+/** Las líneas bloqueantes de un informe del crítico, sin la marca. Puro. */
+export declare function bloqueantesDelInforme(informe: string): string[];
+/** El bloque de texto que ve el agente (y que se le da al crítico como HECHOS). */
+export declare function informeDeGeometria(h: HallazgosDeGeometria, conMaqueta: boolean): string[];
+/**
+ * Los controles que SE VEN en el aparato, en filas de arriba abajo y cada fila de izquierda a derecha: los que
+ * tienen texto, y los botones e imágenes sin él. Es la ESTRUCTURA que se le da a quien describe la captura
+ * (`descripcionDePantalla.ts`), para que describa estos controles y no se invente otros.
+ */
+/**
+ * La caja con la que se mide el ESTILO de un texto del aparato: la suya o la de su ENVOLTORIO. En XOne un botón o una
+ * píldora se hace a menudo con un `<frame>` (fondo, borde, radio) y una etiqueta dentro; la maqueta lo tiene como un
+ * botón o un `<span>` con su borde. Medida la etiqueta, salía «le falta el borde» y otro color de fondo (Maset: SALIR y
+ * el chip «ID»). El envoltorio es el frame MÁS PEQUEÑO que contiene la etiqueta, sin otro texto dentro y con un control
+ * más como mucho (el icono del botón). Una tarjeta, con varios textos, no lo es. El árbol del canal es PLANO: la
+ * contención se deduce de las cajas. Pura.
+ */
+export declare function cajaParaElEstilo(c: ControlDelAparato, g: GeometriaDelAparato): Caja;
+export declare function filasDelAparato(g: GeometriaDelAparato): ControlDelAparato[][];
+export {};

package/dist/core/gestorDeTareas.d.ts

@@ -0,0 +1,295 @@
+/**
+ * El gestor de tareas de un proyecto (IXCODE-11), como PUERTO: el panel del proyecto lista las
+ * pendientes, abre una sesión con una, y al empezar y al cerrar escribe en él —siempre el HARNESS,
+ * con la aprobación de la persona, nunca el agente—. Lo implementan DOS adaptadores, cada uno por
+ * su conector MCP: Jira (`agent/conectores/gestorJira.ts`) y Notion (`gestorNotion.ts`, IXCODE-15);
+ * nada fuera de ellos sabe cuál es.
+ *
+ * Puro: `core/` no importa `@modelcontextprotocol` (`imports.test.ts`).
+ */
+export type CategoriaDeTarea = "por-hacer" | "en-curso" | "terminada";
+export interface Vinculo {
+    /** El id del conector (`jira`, `notion`). */
+    conector: string;
+    /** El sitio del gestor (en Jira, el `cloudId`; en Notion, `SITIO_DE_NOTION`: un espacio por cuenta OAuth). */
+    sitio: string;
+    /** El proyecto en el gestor: en Jira su clave (`IXCODE`); en Notion la URL `collection://…` del data source. */
+    proyecto: string;
+}
+/**
+ * El vínculo tal como se GUARDA en el `config.json` del proyecto (IXCODE-15): el `Vinculo` más si
+ * ese gestor admite «asignadas a mí», decidido UNA vez al vincular —cuando ya se describió la base—
+ * para que `estado` lo lea del disco sin tocar la red.
+ */
+export interface VinculoGuardado extends Vinculo {
+    admiteMias?: boolean;
+    /**
+     * El nombre para MOSTRAR del proyecto vinculado (IXCODE-15), el que el gestor dijo al vincular:
+     * el de la base en Notion (su `proyecto` es un `collection://…` que no se lee), el del proyecto
+     * en Jira. Se guarda con el vínculo para que sobreviva a un reinicio; ausente = no consta (un
+     * vínculo de antes), y entonces no se inventa.
+     */
+    nombreDelProyecto?: string;
+    /**
+     * Qué estado DEL PROYECTO cumple cada papel de una tarea en background (`core/tareasEnElGestor.ts`): xonecode no
+     * impone estados, se adapta a los del flujo. Ausente = la regla por categoría (`transicionPropuesta`).
+     */
+    estados?: MapeoDeEstados;
+    /** Si los tickets de este proyecto DISPARAN tareas solos (la puerta 2). Ausente o `false`: no. Apagado por omisión. */
+    automatico?: boolean;
+    /**
+     * Si, con el disparo encendido, el encargo ampliado ESPERA a que la persona lo revise y mueva el ticket al estado de
+     * lanzar. Ausente o `false` (lo de omisión, decisión suya): se prepara y se lanza en la MISMA pasada, y es xonecode
+     * quien mueve el ticket al empezar.
+     */
+    revisarEncargo?: boolean;
+}
+/** El mapeo de estados: el NOMBRE del estado, tal como lo da el gestor. Cada papel es opcional. */
+export interface MapeoDeEstados {
+    /** Un ticket asignado que entra aquí sin encargo: se amplía y se sube el encargo. */
+    preparar?: string;
+    /** Un ticket asignado que entra aquí sin tarea: se crea la tarea. Y a él pasa una tarea al empezar. */
+    lanzar?: string;
+    /** A él pasa el ticket al terminar la tarea. */
+    terminar?: string;
+}
+/** Un estado del flujo de un proyecto, con su categoría (para proponer el mapeo). */
+export interface EstadoDelGestor {
+    nombre: string;
+    categoria: CategoriaDeTarea;
+}
+/** Un comentario de un ticket: lo que hace falta para leer el último encargo y lo añadido debajo. */
+export interface ComentarioDelGestor {
+    texto: string;
+    /** ISO. Ordena. */
+    creado: string;
+}
+/**
+ * Si se ofrece «asignadas a mí» para un vínculo guardado. Lo guardado manda; ausente —un vínculo
+ * escrito antes de este campo— es `true` para Jira (su `currentUser()` no depende del proyecto) y
+ * `false` para cualquier otro: lo que no se sabe no se ofrece.
+ */
+export declare function admiteMiasDelVinculo(v: VinculoGuardado): boolean;
+/** El único «sitio» de Notion: una cuenta OAuth ve UN espacio, y el MCP no expone su nombre (medido). */
+export declare const SITIO_DE_NOTION = "notion";
+export interface TareaDelGestor {
+    /** Lo que identifica la tarea ante el gestor: en Jira `IXCODE-11`, en Notion el UUID de la página. */
+    clave: string;
+    /** Lo que se ENSEÑA cuando la clave no está hecha para leerse (Notion: el id corto). Ausente = se enseña `clave`. */
+    etiqueta?: string;
+    titulo: string;
+    estado: string;
+    categoria: CategoriaDeTarea;
+    /** Solo el nombre visible: el correo y el id de la cuenta no cruzan el cable. */
+    asignado?: string;
+    /** Para abrirla en el navegador. */
+    url?: string;
+}
+export interface FichaDelGestor extends TareaDelGestor {
+    descripcion: string;
+}
+export interface TransicionDelGestor {
+    id: string;
+    nombre: string;
+    /** El estado al que lleva. */
+    destino: string;
+    categoria: CategoriaDeTarea;
+}
+/** Cómo se acota la consulta de pendientes, además del texto. Todo de LECTURA. */
+export interface OpcionesDePendientes {
+    /** Solo las asignadas a quien tiene la sesión del conector. Ausente o `false`: las de todos. */
+    mias?: boolean;
+}
+/** Un proyecto encontrado por texto (`buscarProyectos`). En Notion `proyecto` es el id de la BASE,
+ *  no su data source: el data source se resuelve al ELEGIRLA (`describirProyecto`), no en la lista. */
+export interface ProyectoEncontrado {
+    proyecto: string;
+    nombre: string;
+    /** Dónde vive, para distinguir dos bases con el mismo nombre («Hypergraph / Projects & Tasks»). */
+    ruta?: string;
+}
+/** Lo que el adaptador ENTENDIÓ del esquema de un proyecto: qué propiedad es el estado, cuál el título y cuál el asignado. */
+export interface EsquemaDelProyecto {
+    /** Lo que se guarda al vincular (en Notion, la URL `collection://…` del data source ya resuelto). */
+    proyecto: string;
+    nombre: string;
+    estado: {
+        propiedad: string;
+        opciones: {
+            nombre: string;
+            categoria: CategoriaDeTarea;
+        }[];
+    };
+    titulo: string;
+    /** Ausente = la base no tiene una propiedad de persona, y entonces no hay «asignadas a mí». */
+    asignado?: string;
+    /** Cuántos data sources tiene la base cuando son VARIOS (se usa el primero, y se dice). */
+    fuentes?: number;
+}
+/** O lo entendido, o por qué esa base no vale como gestor. */
+export type DescripcionDelProyecto = {
+    esquema: EsquemaDelProyecto;
+} | {
+    motivo: string;
+};
+export interface GestorDeTareasPort {
+    sitios(): Promise<{
+        id: string;
+        nombre: string;
+        url?: string;
+    }[]>;
+    proyectos(sitio: string): Promise<{
+        clave: string;
+        nombre: string;
+    }[]>;
+    /**
+     * Buscar proyectos por texto (IXCODE-15). Opcional: Jira no lo implementa —sus proyectos se eligen
+     * de la lista de `proyectos(sitio)`—, y quien no lo tiene contesta con un motivo, no con una lista vacía.
+     */
+    buscarProyectos?(texto: string): Promise<ProyectoEncontrado[]>;
+    /**
+     * Lo que se entiende del esquema de un proyecto (`v.proyecto` puede ser lo que dio `buscarProyectos`
+     * o lo ya vinculado). Opcional: quien lo tiene, `vincular` lo usa para comprobar que el proyecto vale
+     * ANTES de escribir; quien no (Jira), comprueba contra `proyectos(sitio)` como siempre.
+     */
+    describirProyecto?(v: Vinculo): Promise<DescripcionDelProyecto>;
+    /** `opciones.mias`: solo las asignadas a quien tiene la sesión del conector (en Jira, `currentUser()`). */
+    pendientes(v: Vinculo, texto?: string, opciones?: OpcionesDePendientes): Promise<TareaDelGestor[]>;
+    ficha(v: Vinculo, clave: string): Promise<FichaDelGestor>;
+    transiciones(v: Vinculo, clave: string): Promise<TransicionDelGestor[]>;
+    transicionar(v: Vinculo, clave: string, transicion: string): Promise<void>;
+    comentar(v: Vinculo, clave: string, texto: string): Promise<void>;
+    /**
+     * Crear una tarea EN el gestor (una tarea en background de un proyecto vinculado vive ahí, ver
+     * `docs/superpowers/specs/2026-10-15-tareas-desde-el-gestor-design.md`), asignada a quien tiene la sesión del
+     * conector. **Opcional**: quien no lo implementa no ofrece crear en el gestor, y la tarea se encola en local diciéndolo.
+     * Lo propio de cada gestor (el tipo de incidencia de Jira, la propiedad de título de Notion) lo resuelve su adaptador:
+     * aquí no entra nada que no tengan todos.
+     */
+    crear?(v: Vinculo, nueva: NuevaTareaEnElGestor): Promise<TareaDelGestor>;
+    /** Los estados del flujo del proyecto, para elegir el mapeo. Opcional: sin él, el mapeo no se ofrece. */
+    estados?(v: Vinculo): Promise<EstadoDelGestor[]>;
+    /** Los comentarios de un ticket, del más viejo al más nuevo. Opcional: sin él, lanzar usa el texto del ticket. */
+    comentarios?(v: Vinculo, clave: string): Promise<ComentarioDelGestor[]>;
+}
+/** Lo que se le da al gestor para crear una tarea: lo que tienen TODOS. La descripción va en markdown. */
+export interface NuevaTareaEnElGestor {
+    titulo: string;
+    descripcion: string;
+}
+/** Una clave de proyecto de Jira: MAYÚSCULAS, dígitos y `_`, empezando por letra. Entra en una JQL. */
+export declare function motivoDeClaveDeProyecto(clave: string): string | undefined;
+/**
+ * Lo que se ENSEÑA de una clave que no está hecha para leerse (IXCODE-15): el UUID de una página
+ * de Notion (con o sin guiones) se enseña por sus 8 primeros caracteres; cualquier otra clave (la
+ * de Jira, `IXCODE-11`) no tiene etiqueta y se enseña tal cual. UNA regla: el adaptador la usa para
+ * `TareaDelGestor.etiqueta`, y el cliente la REDECLARA para las claves que cruzan sin fila (el
+ * `ticket` de una sesión, `cierre.clave`, `transiciones.clave`).
+ */
+export declare function etiquetaDeClave(clave: string): string | undefined;
+/** Un data source de Notion: `collection://<uuid>`. Es lo que se guarda como `proyecto` del vínculo. */
+export declare function motivoDeFuenteDeNotion(proyecto: string): string | undefined;
+/**
+ * La regla de qué `proyecto` vale, SEGÚN el conector (IXCODE-15): la clave de Jira entra en una JQL,
+ * la URL de Notion en un `notion-fetch` y como tabla de un SQL. Un conector que no es un gestor
+ * conocido no tiene regla que lo acepte. Única, para `config.ts#validar`, `vincular` y los adaptadores.
+ */
+export declare function motivoDeProyectoInaceptable(conector: string, proyecto: string): string | undefined;
+/**
+ * La descripción de la regla, SIN el valor: para un aviso de `config.ts`, que nunca lleva la
+ * entrada (ni siquiera a través del motivo de otra función, que la interpola).
+ */
+export declare function formaDeProyecto(conector: string): string;
+/**
+ * Lo que `describir` acepta de Notion: el id de una BASE (con o sin guiones, como sale de
+ * `notion-search` o de una URL) o un data source ya resuelto. Entra en un `notion-fetch`, no en SQL.
+ */
+export declare function motivoDeReferenciaDeNotion(ref: string): string | undefined;
+/** Cuántas pendientes se piden a Notion de una vez: el mismo tope que en Jira (`PENDIENTES_POR_CONSULTA`). */
+export declare const PENDIENTES_DE_NOTION = 100;
+/**
+ * El SQL de las pendientes de un data source de Notion (IXCODE-15), con `params` para `?`: NUNCA
+ * se interpola un texto de la persona. Los nombres de propiedad vienen del ESQUEMA de Notion (no
+ * del cliente), pero son identificadores y no parámetros, así que se citan con la comilla doblada.
+ *
+ * - Pendiente = estado fuera de los del grupo `complete`, O sin estado (en SQL, `NULL NOT IN (…)`
+ *   no es cierto, y una tarea recién creada sin estado desaparecería). Sin opciones `complete`,
+ *   no hay cláusula: `IN ()` no es SQL.
+ * - `texto`: sobre el título, `LIKE ? ESCAPE '\\'` (medido: el SQLite de Notion acepta ESCAPE).
+ * - `yo`: el id de quien tiene la sesión; la columna de persona es un JSON `["user://…"]` (medido).
+ * - `ORDER BY createdTime DESC`: la tabla que expone el MCP no trae la última edición (medido).
+ */
+export declare function sqlDePendientes(esquema: Pick<EsquemaDelProyecto, "proyecto" | "estado" | "titulo" | "asignado">, texto?: string, opciones?: {
+    yo?: string;
+}): {
+    query: string;
+    params: string[];
+};
+/** La categoría de un GRUPO de estado de Notion: `current`/`future` (y lo desconocido), por hacer. */
+export declare function categoriaDeGrupoDeNotion(grupo: string): CategoriaDeTarea;
+/**
+ * Las pendientes: categoría distinta de terminada, lo último tocado arriba. Con `mias`, solo las
+ * asignadas a quien tiene la sesión del conector: `currentUser()` es una FUNCIÓN de la JQL, no un
+ * texto que venga del cliente, así que no hay nada que escapar — el cliente solo dice sí o no.
+ */
+export declare function jqlDePendientes(v: Pick<Vinculo, "proyecto">, texto?: string, opciones?: OpcionesDePendientes): string;
+/** La categoría de estado del gestor (en Jira, `statusCategory.key`). Lo que no se conoce, por hacer. */
+export declare function categoriaDeEstado(clave: string | undefined): CategoriaDeTarea;
+/**
+ * La transición que se PROPONE en la tarjeta (la persona puede elegir otra o ninguna). Al empezar,
+ * la que lleva a EN CURSO; al cerrar, PROBAR si existe —es el flujo de IXCODE: PROBLEMA → EN CURSO →
+ * PROBAR → PREPROD → TERMINADO—, y si no, la primera que termina.
+ */
+export declare function transicionPropuesta(ts: readonly TransicionDelGestor[], para: "empezar" | "cerrar"): TransicionDelGestor | undefined;
+/**
+ * Lo que hace falta para escribir el comentario de cierre de una tarea (Task 9, IXCODE-11): lo que
+ * `datosDeCierre` (`web/servidor/datosDeCierre.ts`) reúne del disco —ficheros y commits de la
+ * sesión, el último veredicto del verificador, y la última respuesta del asistente— más un `plan`
+ * que hoy nadie compone (ver el comentario de cabecera de `datosDeCierre.ts`). El FORMATO es puro
+ * y vive aquí; una tarea posterior lo manda a Jira con `GestorDeTareasPort.comentar`, tras
+ * aprobación de la persona.
+ */
+export interface DatosDeCierre {
+    ficheros: {
+        ruta: string;
+        clase: "nuevo" | "modificado" | "borrado";
+    }[];
+    commits: string[];
+    /** Ausente = el verificador no corrió en la última ronda: NUNCA se pinta «verde» sin esto. */
+    veredicto?: {
+        verde: boolean;
+        errores: number;
+        avisos: number;
+    };
+    plan?: string;
+    resumen?: string;
+    /**
+     * Qué tan de fiar es la lista de `ficheros`, la MISMA distinción que `CambiosDeSesion.via`
+     * de `agent/sesiones/sesionGit.ts` (redeclarada aquí: `core/` no importa `agent/`). Ausente
+     * mantiene el comportamiento de antes de este campo —la lista tal cual, como si fuera `git`—
+     * para no romper a quien ya llamaba a `comentarioDeCierre` sin saberlo.
+     *
+     * **Por qué esto no es cosmético**: `sin-marca` es una lista VACÍA que NO significa «no
+     * tocaste nada» (`sesionGit.ts#desdeLaApertura`), y `desde-apertura` es el árbol de ahora
+     * contra la foto de apertura —lo normal para un proyecto FUERA del workspace, donde
+     * `commitDeTurno` no commitea nunca— y explícitamente NO es atribución: puede llevar lo que
+     * escribió otra sesión o una tarea de fondo mientras esta estaba abierta. Publicar esa lista
+     * en Jira como «lo que hizo esta sesión» sin decir cuál de las tres es sería la misma mentira
+     * que el comentario de cabecera de `sesionGit.ts` describe para la pestaña Revisión.
+     */
+    atribucion?: "git" | "desde-apertura" | "sin-marca";
+    /**
+     * Lo CRÍTICO de una tarea que se cerró (cortada, sin escribir, un bloqueante visual): va ARRIBA, bajo `## CRITICAL`,
+     * para que nadie lo pase por alto en el ticket. Ausente o vacío = nada crítico.
+     */
+    criticos?: readonly string[];
+    /** Lo que quedó con problemas o detalles (el juez, el verificador): `## Observaciones`, no crítico. */
+    observaciones?: readonly string[];
+}
+/**
+ * El texto del comentario de cierre, en markdown, con lo que el harness sabe de la sesión.
+ * Cuatro secciones fijas —«Qué cambió», «Verificación», y «Plan»/«Resumen» solo si hay algo que
+ * decir— y una firma, para que quien lea el ticket sepa que lo escribió el harness y no una
+ * persona a mano.
+ */
+export declare function comentarioDeCierre(datos: DatosDeCierre): string;

package/dist/core/hechosDelProyecto.d.ts

@@ -0,0 +1,70 @@
+/**
+ * La carta de presentación del proyecto, pegada al turno.
+ *
+ * **Existe por una medida, y la medida es de hoy** (19-09-2026): en seis turnos reales sobre un
+ * proyecto de verdad, cada especialista repetía las MISMAS búsquedas —`grep` ×42 en un solo
+ * turno, con `xnTituloHeaderC` ×7 y `xnHeader` ×3— y el orquestador se llevaba entre el 38 % y
+ * el 50 % del gasto averiguando. No por delegar mal: porque **nadie hace el descubrimiento una
+ * sola vez**. El prompt del orquestador ya PIDE lo contrario («No pidas al siguiente
+ * especialista redescubrir esos hechos») y no basta — una instrucción no es una garantía.
+ *
+ * Así que los hechos baratos se ponen delante en vez de pedirse: el inventario cuesta cientos
+ * de tokens donde abrir los `.xne` cuesta decenas de miles (`xone_navegacion`).
+ *
+ * **Es el patrón de `conAdjuntos` y de `inventarioDelProyecto`**: montar no basta, hay que
+ * DECIR lo que hay. Aquí ni siquiera hay nada montado — el índice existe detrás de una tool
+ * que el agente tiene que acordarse de llamar, y un turno que no la llama trabaja a ciegas.
+ *
+ * **Y se calcula al MANDAR el turno, no al abrir la sesión.** Eso no es un detalle de
+ * cableado: `xone_navegacion` no cachea a propósito porque «un índice viejo que dice que un
+ * campo existe cuando el agente acaba de borrarlo es peor que no tener índice». Congelar esta
+ * foto en el prompt de sistema reintroduciría justo eso. Rehacerla por turno cuesta decenas de
+ * milisegundos y no puede quedarse vieja dentro del turno que la usa.
+ *
+ * Puro y en `core/`: quién lee el disco es de `agent/`.
+ */
+/**
+ * Los hechos que se cuentan. Deliberadamente POCOS y todos baratos de obtener.
+ *
+ * Lo que NO entra, y es una decisión: los CAMPOS de cada colección. Son el grueso del índice,
+ * envejecen dentro del turno —el agente los crea y los borra— y la pregunta «qué campos tiene
+ * X» ya la contesta `xone_navegacion campos` cuando de verdad hace falta. Poner aquí una lista
+ * de campos sería pagar el peaje en cada turno para acertar en pocos.
+ */
+import type { IndiceDeNavegacion } from "./navegacion.js";
+export interface HechosDelProyecto {
+    /** Las colecciones de entrada. Vacío significa NO CONSTA, no «no hay». */
+    entrada: readonly string[];
+    /** Las colecciones de login, si el proyecto tiene. */
+    login: readonly string[];
+    /** Las hojas de estilo declaradas. */
+    estilos: readonly string[];
+    /** Los nombres de todas las colecciones, en el orden en que los da el índice. */
+    colecciones: readonly string[];
+}
+/**
+ * Del índice a los hechos. PURA: el índice entra ya construido.
+ *
+ * Separada de quien lo construye por el motivo de siempre —poder probar la traducción sin
+ * disco— y porque el índice es la AUTORIDAD: aquí solo se elige qué poquito de él se adelanta.
+ * Lo que se elige son las cuatro cosas que un turno cualquiera pregunta primero, y ninguna
+ * lleva rutas: solo NOMBRES, así que esto no puede filtrar una ruta de la máquina por el cable.
+ */
+export declare function hechosDeIndice(indice: IndiceDeNavegacion): HechosDelProyecto;
+/**
+ * Cuántos nombres de colección caben antes de contar el resto.
+ *
+ * Un proyecto real medido tiene 98 colecciones y eso son unos cientos de tokens: barato al
+ * lado de los 18.000 que cuesta enterarse leyendo. El tope existe para que un proyecto mucho
+ * mayor no se coma la ventana, y **lo que no cabe se CUENTA** en vez de recortarse en
+ * silencio: una lista truncada sin decirlo se lee como la lista entera, y entonces el agente
+ * concluye que una colección no existe.
+ */
+export declare const TOPE_DE_COLECCIONES = 150;
+/**
+ * La petición del turno con los hechos del proyecto detrás.
+ *
+ * Sin hechos —no hay índice, o el proyecto no se pudo leer— devuelve la petición TAL CUAL.
+ * Nombrar un inventario que no se tiene sería la mentira con forma de dato de siempre.
+ */
+export declare function conHechosDelProyecto(peticion: string, hechos: HechosDelProyecto | undefined): string;

package/dist/core/hotswap.d.ts

@@ -0,0 +1,30 @@
+/**
+ * El prefijo virtual, con barra final: `CompositeBackend` la exige para no reconstruir
+ * `//nombre` fuera de la raíz montada — la misma trampa medida con `/skills/`.
+ *
+ * **El nombre ata el harness a UNA skill, y eso se declara en vez de disimularse.** Lo
+ * honesto sería un nombre que diga la función y no el protocolo (`/volcados/`), porque
+ * mañana otra skill querrá lo mismo; se deja `hotswap` porque hoy hay exactamente un
+ * escritor, y un nombre genérico con un solo usuario es una abstracción que nadie ha medido.
+ * El día que haya un segundo, el sitio de la decisión es este.
+ */
+export declare const RUTA_HOTSWAP = "/hotswap/";
+/**
+ * Dónde cae en DISCO: al LADO de la de artefactos de la sesión, nunca dentro.
+ *
+ * **Hermana y no subcarpeta**, y eso no es estética: desde que la foto de
+ * `anunciarArtefactosDeLaShell` es recursiva, cualquier cosa que cuelgue de `artefactos/` se
+ * anuncia — o sea que un `artefactos/hotswap/` volvería a llenar la pestaña de volcados, que
+ * es justo lo que esto viene a quitar.
+ *
+ * Se deriva de la carpeta de artefactos en vez de recibir su propio parámetro, por lo mismo
+ * que `carpetaDeDescargas`: esa carpeta ya lleva dentro la única decisión que hace falta
+ * —¿hay una sesión con IDENTIDAD?—, que `turnoReal.ts` resuelve pasando
+ * `.xonecode/sesiones/<id>/artefactos` en la web y cayendo a `.xonecode/artefactos` en el
+ * terminal. Dos parámetros serían dos sitios donde contestar la misma pregunta, y el segundo
+ * es justo el que se cae en un cableado de ocho saltos.
+ *
+ * Y de vivir ahí cuelga gratis lo que si no habría que escribir: `borrarSesion` borra la
+ * carpeta `<id>` entera, así que borrar una conversación se lleva también sus volcados.
+ */
+export declare function carpetaDeHotswap(carpetaDeArtefactos: string): string;