@ancleto/spec 0.10.0 → 0.11.0

package/README.md

@@ -502,6 +502,6 @@ Los 10 agentes instalados y el modelo que usa cada uno según tu tier. Al instal
 
 El tier `minimo` usa un único modelo para los 10 agentes: `deepseek-v4.1-flash` es el más económico del catálogo para coding (0.15 / 0.60 por millón de tokens) y ofrece 1M de contexto.
 
-**Tier `gratis`.** Los 10 agentes usan **Muse Spark 1.3 Free** (`opencode/muse-spark-1.3-contributor-free`) si está disponible en tu cuenta —no está abierto a todos—. En una instalación interactiva el wizard te lo pregunta y la respuesta queda guardada en `.ancletorc` (`gratisModel`) para los siguientes `install`/`update`. Sin TTY se detecta con `opencode models` y, si no se puede confirmar, se usa `opencode/big-pickle`. El instalador siempre informa cuál aplicó.
+**Tier `gratis`.** Los 10 agentes usan **Muse Spark 1.3 Free** (`opencode/muse-spark-1.3-contributor-free`) si está disponible en tu cuenta —no está abierto a todos—. En `install` interactivo el wizard te lo pregunta la primera vez y la respuesta queda guardada en `.ancletorc` (`gratisModel`) para los siguientes `init`/`install`/`update`. `init` interactivo con tier `gratis` pregunta siempre, salvo que `ANCLETO_MUSE_SPARK` fuerce el valor (pre-selecciona el valor guardado o la detección automática como default); fuera del menú reutiliza el valor guardado o detecta con `opencode models` y, si no se puede confirmar, usa `opencode/big-pickle`. Ambos comandos informan cuál aplicaron y, cuando no preguntan, de dónde salió (variable de entorno, valor guardado o detección automática).
 
 > `ANCLETO_MUSE_SPARK=1` fuerza Muse Spark, `ANCLETO_MUSE_SPARK=0` fuerza `big-pickle`. Tiene prioridad sobre la elección guardada.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {
@@ -30,6 +30,10 @@
     "node": ">=24.0.0"
   },
   "license": "MIT",
+  "scripts": {
+    "lint": "eslint src/ test/",
+    "test": "node --test \"test/*.test.js\""
+  },
   "keywords": [
     "opencode",
     "aspec",
@@ -38,5 +42,9 @@
     "agents",
     "skills",
     "spec-driven"
-  ]
+  ],
+  "devDependencies": {
+    "eslint": "^10.11.0",
+    "globals": "^17.13.0"
+  }
 }

package/src/cli/index.js

@@ -9,6 +9,7 @@ import { join, dirname, resolve, basename, relative, isAbsolute } from 'node:pat
 import { fileURLToPath } from 'node:url'
 import { homedir, tmpdir } from 'node:os'
 import { createMemoryEngine, createReadonlyMemoryEngine, defaultMemoryDbPath } from '../core/memory/engine.js'
+import { adaptFrontmatter, parseFrontmatter } from '../core/adapters/frontmatter.js'
 import { writeWorkingContext } from '../core/memory/working-context.js'
 import { memoryDoctor } from '../core/memory/doctor.js'
 import { serveMemoryMcp } from '../core/memory/mcp-server.js'
@@ -74,8 +75,11 @@ Uso:
                                    Imprime/escribe el bloque <ProjectMemoryRules> (reglas activas)
   ancleto memory list [--type X] [--scope X] [--all] [--json]
                                     Lista los nodos de memoria (read-only, no toca la DB)
-  ancleto memory doctor [--rebuild] Diagnostica .ancleto/memory.db (integridad, FTS5, unicidad)
-                                    y reconstruye el indice FTS5 con --rebuild
+ancleto memory doctor [--rebuild] Diagnostica .ancleto/memory.db (integridad, FTS5, unicidad)
+                                     y reconstruye el indice FTS5 con --rebuild
+  ancleto memory export [--out <archivo>]  Exporta nodos activos a JSON (stdout o archivo)
+  ancleto memory import <archivo>          Importa nodos desde JSON (upsert por memory_key, idempotente)
+  ancleto memory gc [--dry-run] [--days N] Purga superseded con antiguedad > N dias (default 30)
   ancleto mcp                           Servidor MCP de memoria propia (stdio) para tu IDE
                                         expone searchMemory, recordRule y recordDecision
   ancleto check                         Verifica integridad de archivos instalados vs manifiesto
@@ -108,7 +112,7 @@ async function readAncletorc(projectDir) {
 
 async function writeManifest(projectDir, extra = {}) {
   const existing = (await readAncletorc(projectDir)) || {}
-  const { version: _legacy, ...rest } = existing
+  const { ...rest } = existing
   const manifest = {
     ...rest,
     schemaVersion: 1,
@@ -195,15 +199,6 @@ async function registerProject(projectDir, { agent, tier } = {}) {
   await writeProjectsRegistry(reg)
 }
 
-async function unregisterProject(projectDir) {
-  const reg = await readProjectsRegistry()
-  const key = normKey(projectDir)
-  if (!reg.projects[key]) return false
-  delete reg.projects[key]
-  await writeProjectsRegistry(reg)
-  return true
-}
-
 // Color helpers (respetan NO_COLOR y TTY).
 const useColor = () => process.stdout.isTTY && !process.env.NO_COLOR
 function paint(code, s) {
@@ -750,6 +745,9 @@ async function resolveAgent(args, existing, allowAsk = Boolean(process.stdin.isT
   if (flag) return flag
   if (existing && SUPPORTED_AGENTS.includes(existing)) return existing
   if (allowAsk) return askAgent()
+  if (existing && !SUPPORTED_AGENTS.includes(existing)) {
+    console.error(`ancleto: advertencia: agente '${existing}' no soportado, usando '${DEFAULT_AGENT}'`)
+  }
   return DEFAULT_AGENT
 }
 
@@ -947,36 +945,6 @@ const AGENT_TARGETS = {
 
 const ANCLETO_SKILLS = ['ancleto-new', 'ancleto-propose', 'ancleto-apply', 'ancleto-verify', 'ancleto-archive', 'ancleto-bulk-archive', 'ancleto-continue', 'ancleto-explore', 'ancleto-ff', 'ancleto-onboard', 'ancleto-workflow']
 
-// Frontmatter: parser propio sin dependencias. Cada entrada conserva su clave y
-// sus lineas crudas (incluye block scalars y mapas anidados), preservando orden.
-function parseFrontmatter(content) {
-  const m = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n?)([\s\S]*)$/.exec(content)
-  if (!m) return { hasFrontmatter: false, content }
-  const entries = []
-  for (const line of m[2].split(/\r?\n/)) {
-    if (/^[A-Za-z0-9_-]+:/.test(line)) {
-      entries.push({ key: line.slice(0, line.indexOf(':')), lines: [line] })
-    } else if (entries.length) {
-      entries[entries.length - 1].lines.push(line)
-    } else {
-      entries.push({ key: null, lines: [line] })
-    }
-  }
-  return { hasFrontmatter: true, open: m[1], entries, close: m[3], nl: m[4], body: m[5] }
-}
-
-function serializeFrontmatter(parsed) {
-  if (!parsed.hasFrontmatter) return parsed.content
-  const inner = parsed.entries.flatMap((e) => e.lines).join('\n')
-  return `${parsed.open}${inner}${parsed.close}${parsed.nl}${parsed.body}`
-}
-
-// D4/D5: hosts cuyo formato de agents difiere del origen requieren adaptacion.
-// Claude/VS Code/Copilot eliminan las claves de opencode; Antigravity usa una
-// transformacion propia (D2). El resto es identidad (preservacion verbatim).
-const AGENT_ADAPTER_HOSTS = new Set(['claude', 'vscode', 'antigravity', 'copilot'])
-const AGENT_ADAPTER_DROP = new Set(['mode', 'color', 'temperature', 'permission', 'model', 'tools'])
-
 // Solo Copilot: los tiers no cambian modelos (el usuario elige en el picker);
 // el orchestrator lo recuerda al empezar.
 const COPILOT_MODEL_NOTE = `
@@ -988,119 +956,6 @@ normal = flujo completo, minimo = pasos agrupados y económicos, gratis = modelo
 gratis disponible en tu cuenta.
 `
 
-// D3: tabla unica (fijada contra la tabla oficial de frontmatter de Custom
-// Subagents) de ids de Antigravity. Conjunto CERRADO: solo se emiten estos ids.
-// Los ids solo-SDK (`find_file`, `edit_file`, `search_web`, `read_url_content`,
-// ...), los de comunidad (`write_to_file`, `call_mcp_tool`,
-// `multi_replace_file_content`, ...) y los de delegacion (`invoke_subagent`,
-// `start_subagent`, `define_subagent`) NO se emiten: no estan confirmados en el
-// frontmatter y un id inexistente cuelga el subagent (Known Issue). Una clave no
-// listada aqui se omite con aviso a stderr, nunca en silencio (D5).
-const ANTIGRAVITY_TOOL_MAP = {
-  read: 'view_file',
-  edit: 'replace_file_content',
-  grep: 'grep_search',
-  bash: 'run_command',
-  todowrite: 'manage_task'
-}
-
-// Hijos directos del mapa `tools:` con su valor crudo (p. ej. `read: true`).
-function parseToolFlags(entry) {
-  const flags = []
-  if (!entry) return flags
-  let childIndent = null
-  for (const line of entry.lines.slice(1)) {
-    const m = /^(\s+)([A-Za-z0-9_-]+):\s*(.*?)\s*$/.exec(line)
-    if (!m) continue
-    if (childIndent === null) childIndent = m[1].length
-    if (m[1].length !== childIndent) continue
-    flags.push({ key: m[2], value: m[3] })
-  }
-  return flags
-}
-
-function frontmatterValue(entry, fallback = null) {
-  if (!entry) return fallback
-  const m = /^[A-Za-z0-9_-]+:\s*(.*?)\s*$/.exec(entry.lines[0] || '')
-  return m ? m[1] : fallback
-}
-
-// D2/D3/D5/D8: adapta el frontmatter de un agent de opencode al de Antigravity.
-// `name` (requerido por el host) se inyecta desde el nombre del archivo. `tools` se
-// emite siempre como lista (el default del host es la lista vacia). Nunca se inventa
-// un id: una clave sin id verificado se omite con aviso (un id inexistente cuelga el
-// subagent).
-function adaptAntigravityFrontmatter(content, name) {
-  const parsed = parseFrontmatter(content)
-  if (!parsed.hasFrontmatter) return content
-  const byKey = (k) => parsed.entries.find((e) => e.key === k)
-  // Claves que el adaptador gestiona: las dropeadas (AGENT_ADAPTER_DROP), las que
-  // re-emite (name/tools/mainAgent/subagent/model/commandExecutionPolicy) y los campos
-  // que preserva del origen (description/skills/mcpServers). Se filtran TODAS del
-  // conjunto conservado para que ninguna pueda quedar duplicada, y se re-emiten una
-  // sola vez en orden determinista, sin importar lo que declare la fuente.
-  const managed = new Set([
-    ...AGENT_ADAPTER_DROP,
-    'name',
-    'description',
-    'mainAgent',
-    'subagent',
-    'commandExecutionPolicy',
-    'mcpServers',
-    'skills'
-  ])
-  // Se conservan las claves extra (no gestionadas); los campos preservados se
-  // re-emiten abajo desde su primera ocurrencia en el origen.
-  const kept = parsed.entries.filter((e) => e.key && !managed.has(e.key))
-
-  const toolIds = []
-  for (const { key, value } of parseToolFlags(byKey('tools'))) {
-    if (value === 'false') continue
-    if (key === 'skill') continue // no es tool: se cubre por `skills`/surfaceo automatico (OQ2)
-    const id = ANTIGRAVITY_TOOL_MAP[key]
-    if (id) {
-      toolIds.push(id)
-      continue
-    }
-    // D3/D5: regla dura. Un id fuera del frontmatter confirmado (exista o no en el
-    // SDK) no se emite: un id inexistente cuelga el subagent. Se omite con aviso,
-    // nunca en silencio. El uso de MCP NO se infiere desde claves desconocidas del
-    // mapa `tools`: se expresa por `mcpServers`/`.agents/mcp_config.json` (D6).
-    console.error(`skip tool '${key}': no verified Antigravity id for agent '${name}'`)
-  }
-
-  const mode = frontmatterValue(byKey('mode'))
-  const mainAgent = mode === 'subagent' ? 'false' : 'true'
-  const subagent = mode === 'primary' ? 'false' : 'true'
-
-  // Orden determinista: name, description, tools, mainAgent, subagent, model,
-  // commandExecutionPolicy, mcpServers, skills, y luego las claves extra conservadas.
-  const out = [{ key: 'name', lines: [`name: ${name}`] }]
-  const description = byKey('description')
-  if (description) out.push(description)
-  out.push({ key: 'tools', lines: [`tools: [${toolIds.join(', ')}]`] })
-  out.push({ key: 'mainAgent', lines: [`mainAgent: ${mainAgent}`] })
-  out.push({ key: 'subagent', lines: [`subagent: ${subagent}`] })
-  out.push({ key: 'model', lines: [`model: inherit`] })
-  out.push({ key: 'commandExecutionPolicy', lines: [`commandExecutionPolicy: sandbox`] })
-  const mcpServers = byKey('mcpServers')
-  if (mcpServers) out.push(mcpServers)
-  const skills = byKey('skills')
-  if (skills) out.push(skills)
-  out.push(...kept)
-  parsed.entries = out
-  return serializeFrontmatter(parsed)
-}
-
-function adaptFrontmatter(content, host, assetKind, name) {
-  if (assetKind !== 'agents' || !AGENT_ADAPTER_HOSTS.has(host)) return content
-  if (host === 'antigravity') return adaptAntigravityFrontmatter(content, name)
-  const parsed = parseFrontmatter(content)
-  if (!parsed.hasFrontmatter) return content
-  parsed.entries = parsed.entries.filter((e) => !(e.key && AGENT_ADAPTER_DROP.has(e.key)))
-  return serializeFrontmatter(parsed)
-}
-
 // D12: asset no soportado -> no se escribe y se avisa a stderr (no bloqueante).
 function warnUnsupportedAsset(asset, agent) {
   console.error(`skip ${asset}: not supported by host '${agent}'`)
@@ -1208,6 +1063,18 @@ function installedExtFor(cat, dirRel) {
   return null
 }
 
+// Host dueno de un directorio instalado por categoria). Para agents los
+// destinos son unicos por host (vscode escribe `.github/agents`, copilot
+// `.github/prompts`), pero commands comparte `.github/prompts` entre ambos:
+// se devuelve el primer match (chequeamos solo agents en el frontmatter check).
+function hostForDir(cat, dirRel) {
+  for (const [host, t] of Object.entries(AGENT_TARGETS)) {
+    const spec = t[cat]
+    if (spec && spec.dir === dirRel) return host
+  }
+  return null
+}
+
 // D9: hosts realmente instalados derivados del manifiesto (union de destinos
 // escritos), no de un unico `rc.agent`. Un proyecto multi-host debe sumar los
 // esperados de todos los hosts para no reportar huerfanos falsos.
@@ -1497,15 +1364,22 @@ async function install(args) {
   }
   if (!language) language = 'auto'
 
-  if (projectDir && !agent) agent = DEFAULT_AGENT
+  if (projectDir && !agent) {
+    if (existingRc?.agent && !SUPPORTED_AGENTS.includes(existingRc.agent)) {
+      console.error(`ancleto: advertencia: agente '${existingRc.agent}' no soportado, usando '${DEFAULT_AGENT}'`)
+    }
+    agent = DEFAULT_AGENT
+  }
   if (!tier) tier = TIERS[storedTier] ? storedTier : 'normal'
 
   let gratisModelChoice = null
+  let gratisModelOrigin = null
   if (tier === 'gratis') {
     const env = envGratisModel()
     const persisted = isKnownGratisModel(existingRc?.gratisModel) ? existingRc.gratisModel : null
     if (env || persisted) {
       gratisModelChoice = env || persisted
+      gratisModelOrigin = env ? 'variable de entorno ANCLETO_MUSE_SPARK' : 'valor guardado en .ancletorc'
     } else if (process.stdout.isTTY) {
       if (!bannerShown) await showBanner()
       const answer = await selectOption('Muse Spark 1.3 Free disponible en tu cuenta?', ['No (usar big-pickle)', 'Si (Muse Spark)'], 0)
@@ -1513,6 +1387,7 @@ async function install(args) {
       gratisModelChoice = answer.startsWith('Si') ? MUSE_SPARK_MODEL : GRATIS_FALLBACK_MODEL
     } else {
       gratisModelChoice = gratisModel()
+      gratisModelOrigin = 'detección automática'
     }
   }
 
@@ -1570,7 +1445,7 @@ async function install(args) {
     : `${target} (disponible en todos tus proyectos)`
   console.log(`ancleto: instalado en ${loc}`)
   console.log(`ancleto: tier de costo de agents: ${tier}`)
-  if (tier === 'gratis') console.log(`ancleto: modelo gratis: ${models.orchestrator}`)
+  if (tier === 'gratis') console.log(`ancleto: modelo gratis: ${models.orchestrator}${gratisModelOrigin ? ` (${gratisModelOrigin})` : ''}`)
   if (res.added.length) {
     console.log(`ancleto: MCP configurados: ${res.added.join(', ')} en ${res.file}`)
   }
@@ -1683,9 +1558,26 @@ async function initProject(args) {
   // Paridad con install: el tier elegido tambien reescribe los modelos de los
   // agentes locales. Antes quedaba huerfano (tier declarado, modelos de otro tier).
   let gratisModelChoice = null
+  let gratisModelOrigin = null
   if (tier === 'gratis') {
+    const env = envGratisModel()
     const persisted = isKnownGratisModel(existing?.gratisModel) ? existing.gratisModel : null
-    gratisModelChoice = persisted || gratisModel()
+    if (env) {
+      gratisModelChoice = env
+      gratisModelOrigin = 'variable de entorno ANCLETO_MUSE_SPARK'
+    } else if (isInteractive) {
+      // En menú interactivo siempre se pregunta: el valor guardado (o la
+      // detección) solo pre-selecciona el default, nunca se aplica en silencio.
+      const defIdx = (persisted || gratisModel()) === MUSE_SPARK_MODEL ? 1 : 0
+      const answer = await selectOption('Muse Spark 1.3 Free disponible en tu cuenta?', ['No (usar big-pickle)', 'Si (Muse Spark)'], defIdx)
+      gratisModelChoice = answer.startsWith('Si') ? MUSE_SPARK_MODEL : GRATIS_FALLBACK_MODEL
+    } else if (persisted) {
+      gratisModelChoice = persisted
+      gratisModelOrigin = 'valor guardado en .ancletorc'
+    } else {
+      gratisModelChoice = gratisModel()
+      gratisModelOrigin = 'detección automática'
+    }
   }
   const written = await installAgentAssets(projectDir, agent)
   if (profile === 'test') await installProfileOverlay(projectDir, agent)
@@ -1717,6 +1609,7 @@ async function initProject(args) {
   if (azure.enabled) console.log(AZURE_MCP_NOTICE)
   if (mcpRes.added.length) console.log(`ancleto: MCP configurados: ${mcpRes.added.join(', ')} en ${mcpRes.file}`)
   console.log(`ancleto: .ancletorc actualizado en ${projectDir} (v${manifest.version})${azure.enabled ? ' (Azure habilitado)' : ' (Azure desactivado)'} (Agente: ${agent})${tier ? ` (Tier: ${tier})` : ''} (Idioma: ${language})`)
+  if (tier === 'gratis' && gratisModelChoice) console.log(`ancleto: modelo gratis: ${gratisModelChoice}${gratisModelOrigin ? ` (${gratisModelOrigin})` : ''}`)
 }
 
 const DEFAULT_IGNORES = ['node_modules', '.git', 'dist']
@@ -2142,6 +2035,88 @@ async function memoryListCmd(flags) {
   console.log(`ancleto: ${nodes.length} nodo(s)`)
 }
 
+async function memoryExport(flags) {
+  const out = flagValue(flags, '--out')
+  const dbPath = defaultMemoryDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no hay memoria en este repo (${dbPath})`)
+    process.exit(1)
+  }
+  const engine = createMemoryEngine(dbPath)
+  try {
+    const nodes = engine.exportActive()
+    const json = JSON.stringify(nodes, null, 2)
+    if (out) {
+      await writeFile(resolve(out), json + '\n')
+      console.log(`ancleto: exportados ${nodes.length} nodo(s) a ${out}`)
+    } else {
+      console.log(json)
+    }
+  } finally {
+    engine.close()
+  }
+}
+
+async function memoryImport(flags) {
+  const positional = flags.find((a) => !a.startsWith('-'))
+  if (!positional) {
+    console.error('ancleto: uso: ancleto memory import <archivo>')
+    process.exit(1)
+  }
+  const file = resolve(positional)
+  if (!(await exists(file))) {
+    console.error(`ancleto: no existe el archivo: ${file}`)
+    process.exit(1)
+  }
+  let json
+  try {
+    json = JSON.parse((await readFile(file, 'utf8')).replace(/^\uFEFF/, ''))
+  } catch (err) {
+    console.error(`ancleto: no se pudo parsear ${file} como JSON: ${err.message}`)
+    process.exit(1)
+  }
+  const dbPath = defaultMemoryDbPath()
+  const engine = createMemoryEngine(dbPath)
+  try {
+    const summary = engine.importNodes(json)
+    console.log(`ancleto: import OK -> insertados:${summary.inserted} actualizados:${summary.updated} omitidos:${summary.skipped}`)
+  } finally {
+    engine.close()
+  }
+}
+
+async function memoryGc(flags) {
+  const dryRun = flags.includes('--dry-run')
+  const daysRaw = flagValue(flags, '--days')
+  let days
+  if (daysRaw !== null) {
+    days = Number(daysRaw)
+    if (!Number.isFinite(days) || days <= 0 || !Number.isInteger(days)) {
+      console.error(`ancleto: --days invalido: ${daysRaw} (entero positivo)`)
+      process.exit(1)
+    }
+  }
+  const dbPath = defaultMemoryDbPath()
+  if (!(await exists(dbPath))) {
+    console.error(`ancleto: no hay memoria en este repo (${dbPath})`)
+    process.exit(0)
+  }
+  const engine = createMemoryEngine(dbPath)
+  try {
+    const result = engine.gcSuperseded({ dryRun, days })
+    if (result.dryRun) {
+      console.log(`ancleto: gc --dry-run (umbral ${result.days} dias) -> ${result.nodes} nodo(s), ~${result.estimated_bytes} bytes a liberar`)
+    } else {
+      console.log(`ancleto: gc (umbral ${result.days} dias) -> ${result.removed} nodo(s) purgados + VACUUM + REINDEX`)
+      if (result.vacuumError) {
+        console.error(`ancleto: advertencia: VACUUM/REINDEX falló: ${result.vacuumError}`)
+      }
+    }
+  } finally {
+    engine.close()
+  }
+}
+
 async function memoryCmd(args) {
   const [sub, ...flags] = args
   if (sub === 'context') {
@@ -2156,10 +2131,25 @@ async function memoryCmd(args) {
     await memoryDoctorCmd(flags)
     return
   }
+  if (sub === 'export') {
+    await memoryExport(flags)
+    return
+  }
+  if (sub === 'import') {
+    await memoryImport(flags)
+    return
+  }
+  if (sub === 'gc') {
+    await memoryGc(flags)
+    return
+  }
   console.error(`ancleto: subcomando de memory desconocido: ${sub || '(ninguno)'}`)
   console.error('ancleto: uso: ancleto memory context [--scope X] [--out file]')
   console.error('ancleto: uso: ancleto memory list [--type X] [--scope X] [--all] [--json]')
   console.error('ancleto: uso: ancleto memory doctor [--rebuild]')
+  console.error('ancleto: uso: ancleto memory export [--out <archivo>]')
+  console.error('ancleto: uso: ancleto memory import <archivo>')
+  console.error('ancleto: uso: ancleto memory gc [--dry-run] [--days <n>]')
   process.exit(1)
 }
 
@@ -2219,6 +2209,13 @@ async function checkCommand() {
         console.log(`  ⚠ ${dirRel}/${f} (huerfano)`)
         orphans++
       }
+      // T3 (delta `frontmatter-adapters`): validacion no bloqueante del frontmatter
+      // de agents contra el adaptador. Solo aplica a `cat === 'agents'` y a archivos
+      // esperados (los huérfanos ya quedan avisados). Reporta como warning (⚠), no como
+      // faltante (✖): el exit code NO se ve alterado por divergencias (solo por faltantes).
+      if (cat === 'agents') {
+        await checkAgentsFrontmatter(cwd, dirRel, actual, expected, ext)
+      }
       if (missingFiles.length === 0 && orphanFiles.length === 0) {
         console.log(`  ✔ ${dirRel} (${actual.length} archivos)`)
       }
@@ -2232,6 +2229,52 @@ async function checkCommand() {
   process.exit(missing > 0 ? 1 : 0)
 }
 
+// T3 (delta `frontmatter-adapters`): para cada `.md` de un directorio de agents
+// instalado, compara el contenido contra `adaptFrontmatter(source, host, 'agents', name)`.
+// Para opencode tambien aplica la sustitucion de `model:` del tier (paso del install que
+// se ejecuta despues del adaptador). Para copilot + orchestrator suma `COPILOT_MODEL_NOTE`.
+// Reporta divergencia como warning (no bloqueante). No compara archivos huérfanos (ya
+// quedan avisados arriba) ni archivos sin origen comparable.
+async function checkAgentsFrontmatter(cwd, dirRel, actual, expected, fileExt) {
+  const host = hostForDir('agents', dirRel)
+  if (!host) return
+  // Mapa de modelos aplicado por install en opencode (model: <x> -> tier).
+  // Para 'gratis' usa el gratisModel persistido en .ancletorc.
+  let tierModelsMap = null
+  if (host === 'opencode') {
+    const tierFile = join(cwd, '.opencode', '.ancleto-tier')
+    if (await exists(tierFile)) {
+      const tier = (await readFile(tierFile, 'utf8')).trim()
+      if (TIERS[tier]) {
+        const rc = await readAncletorc(cwd)
+        const persisted = isKnownGratisModel(rc?.gratisModel) ? rc.gratisModel : null
+        tierModelsMap = tierModels(tier, TIERS, persisted)
+      }
+    }
+  }
+  const nameFromFile = (f) => fileExt ? f.slice(0, -fileExt.length) : f.replace(/\.md$/, '')
+  for (const f of actual) {
+    if (!expected.includes(f)) continue
+    const name = nameFromFile(f)
+    const srcPath = join(ROOT, 'agents', `${name}.md`)
+    if (!(await exists(srcPath))) continue
+    let source = await readFile(srcPath, 'utf8')
+    // Para opencode + tier aplicado, simular la sustitucion que hace applyTier
+    // sobre el campo `model:`. El resto lo gestiona el adaptador (identidad).
+    if (tierModelsMap && tierModelsMap[name]) {
+      source = source.replace(/^model: .*$/m, `model: ${tierModelsMap[name]}`)
+    }
+    let expectedContent = adaptFrontmatter(source, host, 'agents', name)
+    if (host === 'copilot' && name === 'orchestrator') {
+      expectedContent += COPILOT_MODEL_NOTE
+    }
+    const installed = await readFile(join(cwd, dirRel, f), 'utf8')
+    if (installed !== expectedContent) {
+      console.log(`  ⚠ ${dirRel}/${f} (frontmatter diverge del adaptador para host '${host}')`)
+    }
+  }
+}
+
 // Avisa si hay un tier del proyecto sin agentes locales donde aplicarlo:
 // el tier solo se aplica a los agentes instalados en el proyecto, no a los globales.
 async function checkTierOrphan(cwd) {

package/src/core/adapters/frontmatter.js

@@ -0,0 +1,186 @@
+// Modulo puro de adaptacion de frontmatter (D2/D3/D4/D5/D8). Dueno unico de la
+// transformacion del frontmatter: ningun otro punto del CLI SHALL transformarlo.
+// Sin E/S, sin dependencias externas, sin estado global.
+//
+// Contrato publico: `adaptFrontmatter(content, host, assetKind, name)` retorna
+// el contenido completo (frontmatter adaptado + body verbatim). `parseFrontmatter`
+// y `serializeFrontmatter` se re-exportan para que `commandToSkill` en el CLI los
+// pueda usar sin redefinirlos.
+
+export const AGENT_ADAPTER_DROP = new Set(['mode', 'color', 'temperature', 'permission', 'model', 'tools'])
+
+// Hosts conocidos por el modulo. Cualquier host fuera de este conjunto cae en la
+// rama `unknown` (no aborta; emite aviso a stderr y retorna el contenido sin
+// cambios).
+const KNOWN_HOSTS = new Set(['opencode', 'claude', 'vscode', 'antigravity', 'cursor', 'roo', 'copilot'])
+
+// Hosts para los que existe una transformacion documentada de agents
+// (distinta de identidad). Cursor y Roo viven fuera: no hay formato de frontmatter
+// propio, así que la adaptación es passthrough con aviso.
+const TRANSFORM_AGENTS = new Set(['claude', 'vscode', 'antigravity', 'copilot'])
+
+// Tabla unica (fijada contra la tabla oficial de frontmatter de Custom
+// Subagents) de ids de Antigravity. Conjunto CERRADO: solo se emiten estos ids.
+// Los ids solo-SDK (`find_file`, `edit_file`, `search_web`, `read_url_content`,
+// ...), los de comunidad (`write_to_file`, `call_mcp_tool`,
+// `multi_replace_file_content`, ...) y los de delegacion (`invoke_subagent`,
+// `start_subagent`, `define_subagent`) NO se emiten: no estan confirmados en el
+// frontmatter y un id inexistente cuelga el subagent (Known Issue). Una clave no
+// listada aqui se omite con aviso a stderr, nunca en silencio.
+export const ANTIGRAVITY_TOOL_MAP = {
+  read: 'view_file',
+  edit: 'replace_file_content',
+  grep: 'grep_search',
+  bash: 'run_command',
+  todowrite: 'manage_task'
+}
+
+// Parser propio sin dependencias. Cada entrada conserva su clave y sus lineas
+// crudas (incluye block scalars y mapas anidados), preservando orden.
+export function parseFrontmatter(content) {
+  const m = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n?)([\s\S]*)$/.exec(content)
+  if (!m) return { hasFrontmatter: false, content }
+  const entries = []
+  for (const line of m[2].split(/\r?\n/)) {
+    if (/^[A-Za-z0-9_-]+:/.test(line)) {
+      entries.push({ key: line.slice(0, line.indexOf(':')), lines: [line] })
+    } else if (entries.length) {
+      entries[entries.length - 1].lines.push(line)
+    } else {
+      entries.push({ key: null, lines: [line] })
+    }
+  }
+  return { hasFrontmatter: true, open: m[1], entries, close: m[3], nl: m[4], body: m[5] }
+}
+
+export function serializeFrontmatter(parsed) {
+  if (!parsed.hasFrontmatter) return parsed.content
+  const inner = parsed.entries.flatMap((e) => e.lines).join('\n')
+  return `${parsed.open}${inner}${parsed.close}${parsed.nl}${parsed.body}`
+}
+
+// Hijos directos del mapa `tools:` con su valor crudo (p. ej. `read: true`).
+function parseToolFlags(entry) {
+  const flags = []
+  if (!entry) return flags
+  let childIndent = null
+  for (const line of entry.lines.slice(1)) {
+    const m = /^(\s+)([A-Za-z0-9_-]+):\s*(.*?)\s*$/.exec(line)
+    if (!m) continue
+    if (childIndent === null) childIndent = m[1].length
+    if (m[1].length !== childIndent) continue
+    flags.push({ key: m[2], value: m[3] })
+  }
+  return flags
+}
+
+function frontmatterValue(entry, fallback = null) {
+  if (!entry) return fallback
+  const m = /^[A-Za-z0-9_-]+:\s*(.*?)\s*$/.exec(entry.lines[0] || '')
+  return m ? m[1] : fallback
+}
+
+// D2/D3/D5/D8: adapta el frontmatter de un agent de opencode al de Antigravity.
+// `name` (requerido por el host) se inyecta desde el nombre del archivo. `tools` se
+// emite siempre como lista (el default del host es la lista vacia). Nunca se inventa
+// un id: una clave sin id verificado se omite con aviso (un id inexistente cuelga el
+// subagent).
+function adaptAntigravityFrontmatter(content, name) {
+  const parsed = parseFrontmatter(content)
+  if (!parsed.hasFrontmatter) return content
+  const byKey = (k) => parsed.entries.find((e) => e.key === k)
+  // Claves que el adaptador gestiona: las dropeadas (AGENT_ADAPTER_DROP), las que
+  // re-emite (name/tools/mainAgent/subagent/model/commandExecutionPolicy) y los campos
+  // que preserva del origen (description/skills/mcpServers). Se filtran TODAS del
+  // conjunto conservado para que ninguna pueda quedar duplicada, y se re-emiten una
+  // sola vez en orden determinista, sin importar lo que declare la fuente.
+  const managed = new Set([
+    ...AGENT_ADAPTER_DROP,
+    'name',
+    'description',
+    'mainAgent',
+    'subagent',
+    'commandExecutionPolicy',
+    'mcpServers',
+    'skills'
+  ])
+  // Se conservan las claves extra (no gestionadas); los campos preservados se
+  // re-emiten abajo desde su primera ocurrencia en el origen.
+  const kept = parsed.entries.filter((e) => e.key && !managed.has(e.key))
+
+  const toolIds = []
+  for (const { key, value } of parseToolFlags(byKey('tools'))) {
+    if (value === 'false') continue
+    if (key === 'skill') continue // no es tool: se cubre por `skills`/surfaceo automatico
+    const id = ANTIGRAVITY_TOOL_MAP[key]
+    if (id) {
+      toolIds.push(id)
+      continue
+    }
+    // Regla D3/D5. Un id fuera del frontmatter confirmado (exista o no en el
+    // SDK) no se emite: un id inexistente cuelga el subagent. Se omite con aviso,
+    // nunca en silencio. El uso de MCP NO se infiere desde claves desconocidas del
+    // mapa `tools`: se expresa por `mcpServers`/`.agents/mcp_config.json`.
+    console.error(`skip tool '${key}': no verified Antigravity id for agent '${name}'`)
+  }
+
+  const mode = frontmatterValue(byKey('mode'))
+  const mainAgent = mode === 'subagent' ? 'false' : 'true'
+  const subagent = mode === 'primary' ? 'false' : 'true'
+
+  // Orden determinista: name, description, tools, mainAgent, subagent, model,
+  // commandExecutionPolicy, mcpServers, skills, y luego las claves extra conservadas.
+  const out = [{ key: 'name', lines: [`name: ${name}`] }]
+  const description = byKey('description')
+  if (description) out.push(description)
+  out.push({ key: 'tools', lines: [`tools: [${toolIds.join(', ')}]`] })
+  out.push({ key: 'mainAgent', lines: [`mainAgent: ${mainAgent}`] })
+  out.push({ key: 'subagent', lines: [`subagent: ${subagent}`] })
+  out.push({ key: 'model', lines: [`model: inherit`] })
+  out.push({ key: 'commandExecutionPolicy', lines: [`commandExecutionPolicy: sandbox`] })
+  const mcpServers = byKey('mcpServers')
+  if (mcpServers) out.push(mcpServers)
+  const skills = byKey('skills')
+  if (skills) out.push(skills)
+  out.push(...kept)
+  parsed.entries = out
+  return serializeFrontmatter(parsed)
+}
+
+// Elimina las claves gestionadas por el adaptador (mode/color/temperature/
+// permission/model/tools) preservando el resto y el body. Para claude, vscode y
+// copilot. Si no hay frontmatter, retorna el contenido sin cambios.
+function dropManagedKeys(content) {
+  const parsed = parseFrontmatter(content)
+  if (!parsed.hasFrontmatter) return content
+  parsed.entries = parsed.entries.filter((e) => !(e.key && AGENT_ADAPTER_DROP.has(e.key)))
+  return serializeFrontmatter(parsed)
+}
+
+// Punto de entrada publico. Funcion pura (D2/D4): `(content, host, assetKind, name)`
+// → string (contenido completo con frontmatter adaptado + body verbatim).
+// Sin E/S: ni leer ni escribir archivos. Sin estado global mutable.
+//
+// Reglas de dispatch (preservadas del spec `skill-frontmatter-adapters` y
+// extendidas por este change):
+//   opencode                    → identity (passthrough)
+//   antigravity + agents        → adaptAntigravityFrontmatter(content, name)
+//   antigravity + (skills/cmds) → identity
+//   claude/vscode/copilot + ags → dropManagedKeys(content)
+//   claude/vscode/copilot + sk  → identity
+//   cursor/roo                  → identity + aviso stderr (sin formato documentado)
+//   host desconocido            → identity + aviso stderr (no aborta)
+export function adaptFrontmatter(content, host, assetKind, name) {
+  if (!KNOWN_HOSTS.has(host)) {
+    console.error(`unknown agent '${host}', passthrough`)
+    return content
+  }
+  if (host === 'cursor' || host === 'roo') {
+    console.error(`no documented frontmatter adaptation for host '${host}'`)
+    return content
+  }
+  if (assetKind !== 'agents') return content
+  if (!TRANSFORM_AGENTS.has(host)) return content // opencode u otro conocido sin transform
+  if (host === 'antigravity') return adaptAntigravityFrontmatter(content, name)
+  return dropManagedKeys(content)
+}

package/src/core/memory/engine.js

@@ -14,6 +14,23 @@ const SCOPE_HIERARCHY = {
 }
 
 const PUBLIC_COLUMNS = 'n.memory_key, n.type, n.scope, n.content, n.justification, n.created_at'
+const GC_DEFAULT_DAYS = 30
+
+// Sanitizacion best-effort de paths absolutos en texto libre. Cubre los casos
+// pedidos por el spec: `C:\...` en Windows, `/home/...` y `/Users/...` en Unix.
+// No es exhaustiva (se podria perder un path sin barra inicial o con `~`); el
+// usuario debe revisar el archivo antes de compartirlo.
+const ABS_PATH_PATTERNS = [
+  /[A-Za-z]:\\[^\s]*\S/g,
+  /\/home\/[^\s)]+/g,
+  /\/Users\/[^\s)]+/g
+]
+function sanitizePaths(text) {
+  if (!text) return text
+  let out = String(text)
+  for (const re of ABS_PATH_PATTERNS) out = out.replace(re, '<redacted>')
+  return out
+}
 
 const STOPWORDS = new Set([
   'como', 'cómo', 'the', 'a', 'an', 'de', 'del', 'la', 'el', 'los', 'las', 'un', 'una', 'unos', 'unas',
@@ -80,11 +97,23 @@ export function createReadonlyMemoryEngine(dbPath = defaultMemoryDbPath()) {
 function buildEngine(db) {
 
   const findActive = db.prepare(`SELECT id FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
+  const findActiveRow = db.prepare(`SELECT id, created_at FROM memory_nodes WHERE memory_key = ? AND status = 'active'`)
+  const countSuperseded = db.prepare(`SELECT COUNT(*) AS c FROM memory_nodes WHERE memory_key = ? AND status = 'superseded'`)
   const supersede = db.prepare(`UPDATE memory_nodes SET status = 'superseded', superseded_by = ? WHERE id = ? AND status = 'active'`)
   const insertNode = db.prepare(
     `INSERT INTO memory_nodes (id, memory_key, type, scope, status, content, justification, superseded_by, source, confidence, created_at)
      VALUES (?, ?, ?, ?, 'active', ?, ?, NULL, ?, ?, ?)`
   )
+  const listActiveAll = db.prepare(
+    `SELECT memory_key, type, scope, content, justification, created_at FROM memory_nodes WHERE status = 'active' ORDER BY created_at, rowid`
+  )
+  const gcSelect = db.prepare(
+    `SELECT id, length(content) + length(justification) AS size FROM memory_nodes
+     WHERE status = 'superseded' AND created_at < strftime('%Y-%m-%dT%H:%M:%SZ', 'now', '-' || ? || ' days')`
+  )
+  const gcDelete = db.prepare(
+    `DELETE FROM memory_nodes WHERE status = 'superseded' AND created_at < strftime('%Y-%m-%dT%H:%M:%SZ', 'now', '-' || ? || ' days')`
+  )
 
   function buildWorkingContext(scope, maxTokens = MAX_TOKENS, cwd = process.cwd()) {
     const scopes = SCOPE_HIERARCHY[scope] || [scope]
@@ -128,7 +157,7 @@ function buildEngine(db) {
     const lim = Math.min(Math.max(Number(limit) || 10, 1), 50)
     const base = `SELECT ${PUBLIC_COLUMNS} FROM memory_fts f JOIN memory_nodes n ON n.rowid = f.rowid
        WHERE memory_fts MATCH ? AND n.status = 'active'`
-    const run = (match, loose) => {
+    const run = (match, _loose) => {
       const sql = type
         ? db.prepare(`${base} AND n.type = ? ORDER BY rank, n.rowid LIMIT ?`)
         : db.prepare(`${base} ORDER BY rank, n.rowid LIMIT ?`)
@@ -166,7 +195,7 @@ function buildEngine(db) {
     const id = randomUUID()
     const source = String(context.source || 'runtime')
     const confidence = Math.min(Math.max(Number(context.confidence ?? 1), 0), 1)
-    const created_at = new Date().toISOString()
+    const created_at = String(input.createdAt || new Date().toISOString())
 
     db.exec('BEGIN IMMEDIATE')
     let prev = null
@@ -210,6 +239,127 @@ function buildEngine(db) {
     return rows.map((r) => ({ ...publicNode(r), status: r.status }))
   }
 
+  // Devuelve los nodos activos en el formato de export. Sanitiza paths
+  // absolutos en `content` y `justification` antes de serializar. Solo nodos
+  // activos: los superseded son historia interna y no se exportan.
+  function exportActive() {
+    const rows = listActiveAll.all()
+    return rows.map((r) => ({
+      memory_key: r.memory_key,
+      type: r.type,
+      content: sanitizePaths(r.content),
+      justification: sanitizePaths(r.justification),
+      scope: r.scope,
+      createdAt: r.created_at
+    }))
+  }
+
+  // Importa un array validado. Cada entrada hace upsert por memory_key. Por
+  // decision aprobada, los superseded son historia y NO se reactivan: si la
+  // clave solo existe en ese estado, se ignora la entrada. Si existe activa y el
+  // createdAt del JSON es mas reciente, supersede el existente; si es mas
+  // antiguo o igual, no-op (idempotencia). Valida schema antes de procesar y
+  // aborta todo el batch si alguna entrada es invalida.
+  function importNodes(json) {
+    if (!Array.isArray(json)) throw new Error('importNodes: el argumento debe ser un array')
+    const required = ['memory_key', 'type', 'content', 'scope', 'createdAt']
+    for (let i = 0; i < json.length; i++) {
+      const entry = json[i]
+      if (!entry || typeof entry !== 'object') throw new Error(`entry[${i}] invalida: no es objeto`)
+      for (const k of required) {
+        if (entry[k] === undefined || entry[k] === null || entry[k] === '') {
+          throw new Error(`entry[${i}] invalida: falta campo obligatorio "${k}"`)
+        }
+      }
+      if (entry.type !== 'rule' && entry.type !== 'decision') {
+        throw new Error(`entry[${i}].type invalido: ${entry.type}`)
+      }
+      if (typeof entry.createdAt !== 'string' || Number.isNaN(Date.parse(entry.createdAt))) {
+        throw new Error(`entry[${i}].createdAt invalido: ${entry.createdAt}`)
+      }
+    }
+
+    const summary = { inserted: 0, updated: 0, skipped: 0 }
+    db.exec('BEGIN IMMEDIATE')
+    try {
+      for (const entry of json) {
+        const memory_key = String(entry.memory_key).trim()
+        const active = findActiveRow.get(memory_key)
+        if (active) {
+          const incomingTs = Date.parse(entry.createdAt)
+          const existingTs = Date.parse(active.created_at)
+          if (incomingTs > existingTs) {
+            const newId = randomUUID()
+            supersede.run(newId, active.id)
+            insertNode.run(
+              newId, memory_key, entry.type, entry.scope,
+              String(entry.content), String(entry.justification || ''),
+              'import', 1, entry.createdAt
+            )
+            summary.updated++
+          } else {
+            summary.skipped++
+          }
+          continue
+        }
+        const supersededCount = countSuperseded.get(memory_key).c
+        if (supersededCount > 0) {
+          // Decision aprobada: superseded es historia, no se reactiva.
+          summary.skipped++
+          continue
+        }
+        insertNode.run(
+          randomUUID(), memory_key, entry.type, entry.scope,
+          String(entry.content), String(entry.justification || ''),
+          'import', 1, entry.createdAt
+        )
+        summary.inserted++
+      }
+      db.exec('COMMIT')
+    } catch (err) {
+      db.exec('ROLLBACK')
+      throw err
+    }
+    return summary
+  }
+
+  // Purga nodos superseded cuya antiguedad (proxy: created_at, ya que el
+  // schema no expone superseded_at) supere `opts.days`. Con `opts.dryRun` solo
+  // reporta conteo y tamano estimado sin modificar la DB. Sin dryRun ejecuta
+  // el DELETE en transaccion propia y luego VACUUM + REINDEX fuera (SQLite no
+  // permite VACUUM dentro de una transaccion; si falla la compactacion la BD
+  // sigue consistente, solo no se reempaqueta).
+  function gcSuperseded(opts = {}) {
+    const days = Number.isFinite(opts.days) && opts.days > 0 ? Math.floor(opts.days) : GC_DEFAULT_DAYS
+    const dryRun = !!opts.dryRun
+
+    if (dryRun) {
+      const rows = gcSelect.all(days)
+      const nodes = rows.length
+      const estimated_bytes = rows.reduce((acc, r) => acc + Number(r.size || 0), 0)
+      return { dryRun: true, days, nodes, estimated_bytes }
+    }
+
+    db.exec('BEGIN IMMEDIATE')
+    let removed = 0
+    try {
+      const result = gcDelete.run(days)
+      removed = Number(result.changes || 0)
+      db.exec('COMMIT')
+    } catch (err) {
+      db.exec('ROLLBACK')
+      throw err
+    }
+    try {
+      db.exec('VACUUM')
+      db.exec('REINDEX')
+    } catch (err) {
+      // VACUUM/REINDEX son best-effort: si fallan, la BD esta consistente.
+      return { dryRun: false, days, removed, vacuumError: err.message }
+    }
+    return { dryRun: false, days, removed }
+  }
+
   function checkpoint() {
     return checkpointDatabase(db)
   }
@@ -218,5 +368,5 @@ function buildEngine(db) {
     db.close()
   }
 
-  return { buildWorkingContext, searchMemory, recordNode, listNodes, checkpoint, close }
+  return { buildWorkingContext, searchMemory, recordNode, listNodes, exportActive, importNodes, gcSuperseded, checkpoint, close }
 }