orquestra-mcp 1.74.0 → 1.76.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orquestra-mcp",
-  "version": "1.74.0",
+  "version": "1.76.0",
   "description": "Servidor MCP de Orquestra -- 161 tools para leer y escribir tareas, ideas, changelog, infraestructura, contenido, QA y más desde un agente de IA",
   "type": "module",
   "bin": {

package/src/designFlow.mjs

@@ -0,0 +1,296 @@
+// ORQ-564: flujo guiado para llenar el módulo Diseño / UI. Datos estáticos, sin red
+// (get_design_flow) + lógica pura de estado (computeDesignStatus, usada por get_design_status).
+// El contenido largo vive aquí, en el VALOR que devuelve la tool, no en su descripción.
+
+export const DESIGN_PLATFORMS = ['web', 'ios', 'android']
+
+const PRINCIPLES = [
+  'La web es la referencia: se carga primero y las demás plataformas reutilizan sus keys (list_design_nav platform=web).',
+  'No inventes: registra solo lo que está en el código real de la plataforma (router, tab bar, temas, componentes).',
+  'Un agente por plataforma a la vez. Evita cargas simultáneas del mismo nombre/key en el mismo catálogo (tokens, componentes): se pisan.',
+  'Lotes compactos: tokens ≤100, nodos de navegación ≤40, componentes ≤200 por llamada; deja compact=true.',
+  'Los nodos no se borran: se actualizan (upsert). Borrar es la excepción y solo con confirmación del usuario.',
+  'Revisa siempre los `warnings` de la respuesta (tokens o usedIn inexistentes) y corrígelos antes de seguir.',
+  'upsert_design_nav y upsert_design_components MEZCLAN actions/states/platforms por key; update_design_nav_node y update_design_component REEMPLAZAN el array completo.',
+  'No crees tareas (create_parity_tasks, create_task) sin confirmar antes con el usuario.',
+  'Cada paso termina cuando get_design_status lo confirma (el campo `next` avanza), no cuando tú lo sientes terminado.',
+  'Antes de crear cualquier cosa llama a list_* para no duplicar.',
+]
+
+const GLOSSARY = {
+  actions: {
+    convention: 'entidad.verbo (task.create, project.archive). La misma operación lleva la MISMA key en web, iOS y Android.',
+    verbs: ['create', 'edit', 'delete', 'filter', 'search', 'sort', 'export', 'share', 'assign', 'comment', 'convert', 'archive', 'restore', 'open-detail', 'reorder', 'import', 'change-view'],
+  },
+  states: {
+    note: 'Registra solo los que existan en el código de esa pantalla.',
+    list: ['loading', 'empty', 'error', 'readonly', 'no-access', 'offline', 'refreshing', 'search-empty'],
+  },
+  blocks: [
+    'Encabezado', 'Búsqueda', 'Filtros', 'Pestañas', 'Contenido de pestaña', 'Lista', 'Tablero', 'Tarjeta de elemento',
+    'Estado vacío', 'Estado de error', 'Aviso', 'Acciones', 'Formulario', 'KPIs / Métricas', 'Resumen', 'Actividad reciente',
+    'Navegación', 'Primeros pasos', 'Vista por rol', 'Asistente IA', 'Módulos', 'Plataformas / Infraestructura', 'Miembros',
+    'Cuenta y sesión', 'Ajustes',
+  ],
+  components: [
+    'Button', 'Card', 'Modal', 'Drawer', 'Input', 'Select', 'Checkbox', 'Toggle', 'Badge', 'Chip', 'Tabs', 'SegmentedControl',
+    'ListRow', 'EmptyState', 'Toast', 'Banner', 'Avatar', 'DropdownMenu', 'ProgressBar', 'Tooltip', 'Topbar', 'Sidebar',
+    'SearchBar', 'ConfirmDialog', 'DatePicker',
+  ],
+}
+
+const STEPS = [
+  {
+    order: 1, id: 'check', title: 'Revisar qué ya existe',
+    goal: 'Saber qué hay cargado en Diseño / UI para no duplicar ni pisar nada.',
+    tools: ['get_design_status', 'list_design_tokens', 'list_design_nav', 'list_design_components'],
+    how: [
+      'Llama get_design_status: da conteos por plataforma y el primer paso pendiente (`next`).',
+      'Si vas a trabajar una plataforma con datos previos, haz list_design_tokens / list_design_nav / list_design_components con ese platform antes de crear.',
+      'Decide la plataforma de esta pasada (una por agente) y empieza por el `next` que indique el estado.',
+    ],
+    doneWhen: 'Sabes qué plataforma vas a trabajar y cuál es su primer paso pendiente.',
+    pitfalls: ['Crear sin listar primero genera duplicados.', 'Empezar por iOS/Android sin que la web tenga navegación cargada.'],
+  },
+  {
+    order: 2, id: 'identity', title: 'Identidad: design tokens',
+    goal: 'Registrar colores, tipografía, radios, sombras, espaciado, iconos y logo de la plataforma.',
+    tools: ['list_design_tokens', 'upsert_design_tokens', 'create_design_token', 'update_design_token'],
+    how: [
+      'Lee los archivos que DEFINEN el tema (web: theme/tokens.css/variables.css; iOS: Colors.swift/Theme; Android: Color.kt/Theme.kt), no los que lo usan.',
+      'Usa nombres compartidos entre plataformas: brand, surface, page-bg, border, text-primary, text-secondary, text-tertiary, text-disabled, danger, success, warning, ai, radius-sm, radius-md, radius-lg, radius-pill, font-sans.',
+      'Cada token: kind (color|typography|radius|shadow|spacing|icon-set|logo), value (modo claro) y valueDark si existe, platform, group y sourceRef (archivo y símbolo).',
+      'Carga con upsert_design_tokens en lotes de hasta 100.',
+      'Verifica con get_design_status (tokens > 0 para la plataforma).',
+    ],
+    doneWhen: 'get_design_status muestra tokens > 0 para la plataforma y los nombres coinciden con los de la web.',
+    pitfalls: ['Registrar valores hex que no están en el archivo del tema.', 'Nombres distintos por plataforma para lo mismo (impide comparar paridad).', 'Olvidar valueDark cuando el tema tiene modo oscuro.'],
+  },
+  {
+    order: 3, id: 'navigation', title: 'Navegación: árbol de pantallas',
+    goal: 'Registrar el árbol de menús, secciones, pantallas, pestañas, acciones y overlays con keys estables entre plataformas.',
+    tools: ['list_design_nav', 'upsert_design_nav', 'update_design_nav_node', 'reorder_design_nav'],
+    how: [
+      'Lee el router (web), el tab bar / NavigationStack (iOS) o el NavHost / bottom bar (Android) y el drawer o sidebar si existe.',
+      'Cada nodo: kind (menu|section|screen|tab|action|overlay), name, key estable, parentKey, route.',
+      'La WEB va primero y es la referencia. iOS y Android primero llaman list_design_nav platform=web y REUTILIZAN sus keys para las mismas pantallas; solo inventan keys para lo propio de su plataforma.',
+      'Carga con upsert_design_nav en lotes de hasta 40 nodos (el padre puede ir en el mismo lote).',
+      'Verifica con get_design_status (navNodes > 0).',
+    ],
+    doneWhen: 'navNodes > 0 y todas las pantallas del router/tab bar están cargadas con keys alineadas a la web.',
+    pitfalls: ['Keys nuevas en iOS/Android para pantallas que ya existen en web.', 'Pantallas sin parentKey (quedan en la raíz).', 'Lotes de más de 40 nodos.'],
+  },
+  {
+    order: 4, id: 'blocks', title: 'Bloques de cada pantalla',
+    goal: 'Describir cada pantalla (kind screen/tab) como bloques de arriba a abajo.',
+    tools: ['upsert_design_nav', 'update_design_nav_node'],
+    how: [
+      'Abre el código de cada pantalla y lista sus bloques en orden visual, de arriba a abajo.',
+      'Usa los nombres del glosario (glossary.blocks) cuando el bloque sea genérico: Encabezado, Lista, Filtros, Estado vacío, etc. Para algo propio, un nombre corto y descriptivo.',
+      'Cada bloque lleva name y, opcional, description corta.',
+      'Actualiza con upsert_design_nav (misma platform+key): no se duplican nodos.',
+    ],
+    doneWhen: 'Al menos 50% de las pantallas tienen bloques (idealmente todas) según get_design_status.',
+    pitfalls: ['Describir el diseño ideal en vez del código real.', 'Nombres de bloque distintos para lo mismo entre plataformas.'],
+  },
+  {
+    order: 5, id: 'actions-states', title: 'Acciones y estados por pantalla',
+    goal: 'Registrar qué puede hacer el usuario en cada pantalla y qué estados maneja; es lo que compara la paridad.',
+    tools: ['upsert_design_nav', 'update_design_nav_node'],
+    how: [
+      'Acciones con key entidad.verbo (ej. task.create) y verbos estándar: create, edit, delete, filter, search, sort, export, share, assign, comment, convert, archive, restore, open-detail, reorder, import, change-view.',
+      'Estados: loading, empty, error, readonly, no-access, offline, refreshing, search-empty. Solo los que existan en el código de esa pantalla.',
+      'Misma key para la misma operación en las tres plataformas.',
+      'upsert_design_nav MEZCLA actions/states por key; no repitas los ya cargados innecesariamente.',
+    ],
+    doneWhen: 'Al menos 50% de las pantallas tienen acciones (y estados donde aplique) según get_design_status.',
+    pitfalls: ['Registrar estados que la pantalla no maneja.', 'Verbos distintos para la misma operación (delete vs remove).', 'Usar update_design_nav_node y reemplazar sin querer el array completo.'],
+  },
+  {
+    order: 6, id: 'components', title: 'Catálogo de componentes',
+    goal: 'Catalogar los componentes de UI reales con su referencia en código por plataforma.',
+    tools: ['list_design_components', 'upsert_design_components', 'update_design_component'],
+    how: [
+      'Usa nombres canónicos: Button, Card, Modal, Drawer, Input, Select, Checkbox, Toggle, Badge, Chip, Tabs, SegmentedControl, ListRow, EmptyState, Toast, Banner, Avatar, DropdownMenu, ProgressBar, Tooltip, Topbar, Sidebar, SearchBar, ConfirmDialog, DatePicker.',
+      'platforms[] con la platform de esta pasada y su sourceRef (archivo y símbolo).',
+      'tokens y usedIn SOLO con nombres de tokens y keys de nav que ya existen (list_design_tokens, list_design_nav).',
+      'Carga con upsert_design_components; revisa `warnings` y corrige.',
+      'UN agente a la vez por catálogo: cargar el mismo name desde otra plataforma mezcla, pero en paralelo se pisan.',
+    ],
+    doneWhen: 'components > 0 para la plataforma y `warnings` vacío.',
+    pitfalls: ['Inventar tokens o usedIn que no existen.', 'Dos agentes cargando componentes al mismo tiempo.', 'Nombres distintos al canónico para el mismo componente.'],
+  },
+  {
+    order: 7, id: 'parity', title: 'Paridad entre plataformas',
+    goal: 'Revisar huecos entre web, iOS y Android y fijar los que no aplican.',
+    tools: ['get_design_parity', 'set_design_parity_cell', 'create_parity_tasks'],
+    how: [
+      'Llama get_design_parity con soloHuecos:true.',
+      'Contenedores propios de cada plataforma (sidebar, tabbar, drawer, toolbar, grupos) se fijan not_applicable con set_design_parity_cell y un `reason` (obligatorio).',
+      'Los huecos reales (different/missing) NO se corrigen aquí: preséntalos al usuario. Solo con su confirmación conviértelos en tareas con create_parity_tasks (máx. 50 por llamada).',
+    ],
+    doneWhen: 'Los huecos que quedan son reales y el usuario decidió qué hacer con ellos.',
+    pitfalls: ['Crear tareas sin confirmar.', 'Marcar not_applicable sin motivo (la API lo rechaza).', 'Marcar not_applicable un hueco real para que "salga verde".'],
+  },
+  {
+    order: 8, id: 'drift', title: 'Deriva de tokens',
+    goal: 'Detectar valores de diseño escritos a mano fuera de los tokens.',
+    tools: ['report_design_drift', 'list_design_drift', 'update_design_drift', 'resolve_missing_design_drift'],
+    how: [
+      'Guarda la hora de inicio de la pasada (Date.now()).',
+      'Recorre el código de UNA plataforma buscando hex, radios, spacings y fuentes sueltos; ignora el archivo de definición del tema, tests, previews y valores dinámicos.',
+      'Compara cada valor con los tokens de esa misma plataforma y propón suggestedToken si coincide.',
+      'Reporta en lote con report_design_drift (hasta 200 por llamada).',
+      'Solo tras una pasada COMPLETA, resolve_missing_design_drift en dryRun (platform + reportedBefore = hora de inicio); si es correcto, repite con dryRun:false.',
+    ],
+    doneWhen: 'La pasada completa de la plataforma está reportada y los hallazgos resueltos ya no aparecen.',
+    pitfalls: ['Resolver sin haber terminado la pasada completa.', 'Reportar el archivo del tema como deriva.', 'Mezclar plataformas en una misma pasada.'],
+  },
+  {
+    order: 9, id: 'sync', title: 'Sincronía con el código (mantenimiento)',
+    goal: 'Detectar qué cambió en el código desde la última carga de Diseño / UI y mantener el catálogo al día.',
+    tools: ['check_design_sync', 'mark_design_synced', 'upsert_design_nav', 'upsert_design_components'],
+    how: [
+      'Línea base: tras una carga completa de la plataforma, corre mark_design_synced con all:true (platform + repoPath absoluto del repo) para guardar la huella de cada archivo citado en sourceRef.',
+      'Después, corre check_design_sync periódicamente o tras merges: compara la huella local con la guardada y marca como outdated lo que cambió.',
+      'Los `changed` se vuelven a leer en el código y se actualizan con upsert_design_nav / upsert_design_components.',
+      'Luego mark_design_synced SOLO de esos (nav: keys, components: nombres) para sellar la nueva huella y limpiar outdated.',
+      'Nada se borra solo: un archivo que ya no existe aparece como no-existe y lo decide el usuario.',
+    ],
+    doneWhen: 'check_design_sync no reporta `changed` ni `baselineMissing` para la plataforma.',
+    pitfalls: ['Usar mark_design_synced sin haber revisado lo que cambió (oculta el cambio).', 'Pasar el repoPath de otra plataforma.', 'Borrar nodos porque su archivo no existe sin confirmar con el usuario.'],
+  },
+  {
+    order: 10, id: 'screenshots', title: 'Capturas (opcional)',
+    goal: 'Adjuntar capturas a las pantallas clave.',
+    tools: ['add_design_screenshot', 'remove_design_screenshot'],
+    how: [
+      'Para cada pantalla clave: add_design_screenshot con platform, key del nodo y la ruta del archivo (png/jpg/webp ≤5 MB).',
+      'Para marketing, nunca captures el workspace real: usa un usuario demo con datos poblados.',
+    ],
+    doneWhen: 'Las pantallas clave tienen captura, o el usuario decide omitir este paso.',
+    pitfalls: ['Capturas con datos reales de clientes.', 'Archivos fuera de png/jpg/webp o mayores a 5 MB.'],
+  },
+]
+
+const PLATFORM_LABEL = { web: 'web (React)', ios: 'iOS (Swift)', android: 'Android (Kotlin)' }
+
+function adjustStep(step, platform) {
+  const s = { ...step, how: [...step.how], pitfalls: [...step.pitfalls], tools: [...step.tools] }
+  if (step.id === 'navigation' && platform !== 'web') {
+    s.how.unshift('PRIMERO lee list_design_nav platform=web (tree o plano) y reutiliza sus keys para las mismas pantallas.')
+  }
+  if (step.id === 'navigation' && platform === 'web') {
+    s.how.unshift('Eres la referencia: define keys estables y claras (iOS y Android las reutilizarán).')
+  }
+  if (step.id === 'drift' || step.id === 'identity' || step.id === 'components') {
+    s.how.push(`Trabaja SOLO platform=${platform} en esta pasada.`)
+  }
+  return s
+}
+
+function buildAgentPrompt(platform, steps) {
+  const ids = steps.map(s => `${s.order}. ${s.id}`).join('; ')
+  const webNote = platform === 'web'
+    ? 'La web es la referencia: define keys y nombres estables, porque iOS y Android los reutilizarán.'
+    : 'Antes de crear nodos lee list_design_nav platform=web y reutiliza sus keys; la web es la referencia.'
+  return [
+    `Vas a llenar el módulo Diseño / UI de Orquestra para la plataforma ${PLATFORM_LABEL[platform]}, leyendo su código real. Trabaja SOLO esta plataforma y no inventes nada que no esté en el código.`,
+    webNote,
+    `Pasos en orden (ids de get_design_flow): ${ids}.`,
+    'Empieza llamando get_design_status: su campo `next` te dice el primer paso pendiente de tu plataforma. Para cada paso llama get_design_flow con step=<id> y sigue sus `how`, usando los `tools` indicados.',
+    'Reglas: llama list_* antes de crear para no duplicar; lotes compactos (tokens ≤100, nodos ≤40, componentes ≤200); revisa los `warnings`; no borres nodos, actualízalos; no crees tareas sin confirmar con el usuario; un paso termina cuando get_design_status lo confirma.',
+    'Al terminar cada paso vuelve a llamar get_design_status y avanza al nuevo `next`. Cuando todo esté cargado, resume al usuario los huecos de paridad y la deriva abierta y pregúntale qué hacer.',
+  ].join('\n')
+}
+
+export const DESIGN_PLATFORM_ARGS = ['web', 'ios', 'android', 'all']
+export const STEP_IDS = STEPS.map(s => s.id)
+
+// Devuelve { error } si el step no existe (la tool lo convierte en un 404 amable).
+export function getDesignFlow({ platform = 'all', step } = {}) {
+  const adjust = platform === 'all' ? s => s : s => adjustStep(s, platform)
+  const base = { version: 1, platform, principles: PRINCIPLES, glossary: GLOSSARY }
+  if (step) {
+    const found = STEPS.find(s => s.id === step)
+    if (!found) return { error: `Error (404): no existe el paso "${step}". Pasos disponibles: ${STEP_IDS.join(', ')}.` }
+    return { ...base, steps: [adjust(found)] }
+  }
+  const steps = STEPS.map(adjust)
+  const out = { ...base, steps }
+  if (platform !== 'all') out.agentPrompt = buildAgentPrompt(platform, steps)
+  return out
+}
+
+// ── get_design_status: lógica pura sobre las respuestas de la API ──────────────
+const arr = r => (Array.isArray(r) ? r : Array.isArray(r?.items) ? r.items : [])
+const nonEmpty = a => Array.isArray(a) && a.length > 0
+const isScreen = n => n?.kind === 'screen' || n?.kind === 'tab'
+
+function pickParity(parity, platform) {
+  const s = parity?.summary
+  const row = s?.[platform] || s?.byPlatform?.[platform]
+  if (!row || typeof row !== 'object') return null
+  const n = k => Number(row[k] ?? row[k.replace('_', '')] ?? 0) || 0
+  return { same: n('same'), different: n('different'), missing: n('missing'), not_applicable: n('not_applicable') }
+}
+
+function nextStep(p) {
+  if (!p.tokens) return { next: 'identity', reason: 'No hay design tokens cargados para esta plataforma.' }
+  if (!p.navNodes) return { next: 'navigation', reason: 'No hay nodos de navegación cargados para esta plataforma.' }
+  const screens = p.screens
+  if (screens && p.screensWithBlocks < screens / 2) return { next: 'blocks', reason: `Solo ${p.screensWithBlocks} de ${screens} pantallas tienen bloques (meta: al menos 50%).` }
+  if (screens && p.screensWithActions < screens / 2) return { next: 'actions-states', reason: `Solo ${p.screensWithActions} de ${screens} pantallas tienen acciones (meta: al menos 50%).` }
+  if (!p.components) return { next: 'components', reason: 'No hay componentes catalogados para esta plataforma.' }
+  const par = p.parity
+  if (par && (par.different + par.missing) > 0) return { next: 'parity', reason: `Hay ${par.different + par.missing} huecos de paridad (different/missing) por revisar.` }
+  if (p.driftOpen > 0) return { next: 'drift', reason: `Hay ${p.driftOpen} hallazgos de deriva abiertos.` }
+  return { next: 'parity', reason: 'Lo básico está cargado; revisa la paridad y, si quieres, corre la pasada de deriva (drift).' }
+}
+
+// results: { tokens, nav: {web,ios,android}, components, drift, parity } — cada uno puede ser { error }
+export function computeDesignStatus(results) {
+  const errors = []
+  const ok = (key, v) => { if (v?.__error) { errors.push({ source: key, error: v.__error }); return null } return v }
+  const tokens = arr(ok('tokens', results.tokens))
+  const components = arr(ok('components', results.components))
+  const driftRaw = ok('drift', results.drift)
+  const drift = arr(driftRaw)
+  const parity = ok('parity', results.parity)
+  const syncRes = {}
+  for (const pl of DESIGN_PLATFORMS) syncRes[pl] = ok(`sync:${pl}`, results.sync?.[pl])
+  const platforms = {}
+  for (const pl of DESIGN_PLATFORMS) {
+    const nav = arr(ok(`nav:${pl}`, results.nav?.[pl]))
+    const screens = nav.filter(isScreen)
+    const p = {
+      tokens: tokens.filter(t => (t.platform || 'all') === pl || t.platform === 'all' || !t.platform).length,
+      navNodes: nav.length,
+      screens: screens.length,
+      screensWithBlocks: screens.filter(n => nonEmpty(n.blocks)).length,
+      screensWithActions: screens.filter(n => nonEmpty(n.actions)).length,
+      screensWithStates: screens.filter(n => nonEmpty(n.states)).length,
+      components: components.filter(c => arr(c.platforms).some(x => x?.platform === pl)).length,
+      driftOpen: drift.filter(d => d.platform === pl && (d.status || 'open') === 'open').length,
+      parity: pickParity(parity, pl),
+    }
+    if (!drift.length && driftRaw?.summary?.byPlatform?.[pl] != null) {
+      const bp = driftRaw.summary.byPlatform[pl]
+      p.driftOpen = typeof bp === 'number' ? bp : Number(bp?.open ?? 0)
+    }
+    const sy = syncRes[pl]
+    if (sy) {
+      const sum = k => Number(sy.summary?.nav?.[k] ?? 0) + Number(sy.summary?.components?.[k] ?? 0)
+      p.sync = { withHash: sum('withHash'), outdated: sum('outdated'), stale: sum('stale') }
+    }
+    Object.assign(p, nextStep(p))
+    if (p.sync?.outdated > 0) {
+      p.next = 'sync'
+      p.reason = `Hay ${p.sync.outdated} elementos marcados como desactualizados respecto al código; revísalos con check_design_sync.`
+    }
+    platforms[pl] = p
+  }
+  const out = { platforms, parity: { capabilitiesNodes: parity?.capabilitiesNodes ?? null } }
+  if (errors.length) out.errors = errors
+  return out
+}

package/src/designSync.mjs

@@ -0,0 +1,148 @@
+// ORQ-575: detección de cambios del código desde la última carga de Diseño / UI.
+// Lógica pura y testeable: huellas locales (sha1 de los bytes) de los archivos que citan los
+// sourceRef, comparadas con el sourceHash guardado en Orquestra. Las funciones reciben la API
+// por parámetro (io) para poder probarlas sin red.
+import { createHash } from 'node:crypto'
+import { readFileSync, realpathSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+export const MAX_FILE_BYTES = 2 * 1024 * 1024
+export const BATCH_SIZE = 40
+export const LIST_CAP = 100
+
+const PATH_RE_ORDERED = /[\w@.\-/]+\.(?:json|jsx|js|tsx|ts|mjs|cjs|css|swift|kts|kt|xml|md)(?![\w])/
+
+// Primer fragmento con pinta de ruta de archivo dentro de un sourceRef, o null.
+export function extractSourcePath(sourceRef) {
+  if (typeof sourceRef !== 'string') return null
+  const m = sourceRef.match(PATH_RE_ORDERED)
+  return m ? m[0] : null
+}
+
+// → { status: 'ok', hash } | { status: 'no-existe' | 'fuera-del-repo' | 'demasiado-grande' }
+export function hashFile(repoPath, relPath) {
+  let repoReal
+  try { repoReal = realpathSync(repoPath) } catch { return { status: 'no-existe' } }
+  const inside = p => p === repoReal || p.startsWith(repoReal + path.sep)
+  const lexical = path.resolve(repoReal, relPath)
+  if (!inside(lexical)) return { status: 'fuera-del-repo' }
+  let real
+  try { real = realpathSync(lexical) } catch { return { status: 'no-existe' } }
+  if (!inside(real)) return { status: 'fuera-del-repo' }
+  let st
+  try { st = statSync(real) } catch { return { status: 'no-existe' } }
+  if (!st.isFile()) return { status: 'no-existe' }
+  if (st.size > MAX_FILE_BYTES) return { status: 'demasiado-grande' }
+  try {
+    return { status: 'ok', hash: createHash('sha1').update(readFileSync(real)).digest('hex') }
+  } catch { return { status: 'no-existe' } }
+}
+
+const chunk = (a, n) => { const out = []; for (let i = 0; i < a.length; i += n) out.push(a.slice(i, i + n)); return out }
+const arr = v => (Array.isArray(v) ? v : [])
+
+const STATUS_BUCKET = {
+  unchanged: 'unchanged', changed: 'changed', 'baseline-missing': 'baselineMissing',
+  'no-existe': 'missing', 'fuera-del-repo': 'outsideRepo', 'demasiado-grande': 'tooBig', 'sin-ruta': 'noPath',
+}
+
+// Clasifica un item de /v1/design-sync contra el repo local. cache: Map ruta → resultado de hashFile.
+export function classifyItem(item, repoPath, cache = new Map()) {
+  const rel = extractSourcePath(item?.sourceRef)
+  if (!rel) return { state: 'sin-ruta', path: null }
+  if (!cache.has(rel)) cache.set(rel, hashFile(repoPath, rel))
+  const h = cache.get(rel)
+  if (h.status !== 'ok') return { state: h.status, path: rel }
+  if (!item.sourceHash) return { state: 'baseline-missing', path: rel, hash: h.hash }
+  return { state: h.hash === item.sourceHash ? 'unchanged' : 'changed', path: rel, hash: h.hash }
+}
+
+function emptySummary() {
+  return { unchanged: 0, changed: 0, baselineMissing: 0, missing: 0, outsideRepo: 0, tooBig: 0, noPath: 0 }
+}
+
+// io: { fetchSync(), fetchCategories(), writeNav(nodes), writeComponents(components) }
+export async function runCheck({ platform, repoPath, record = true }, io) {
+  const data = await io.fetchSync()
+  const nav = arr(data?.nav)
+  const components = arr(data?.components)
+  const cache = new Map()
+  const summary = { nav: emptySummary(), components: emptySummary() }
+  const changed = []
+  const toMark = { nav: [], components: [] }
+  for (const [kind, list] of [['nav', nav], ['component', components]]) {
+    for (const it of list) {
+      const c = classifyItem(it, repoPath, cache)
+      summary[kind === 'nav' ? 'nav' : 'components'][STATUS_BUCKET[c.state]]++
+      if (c.state === 'changed') {
+        changed.push({ kind, ...(kind === 'nav' ? { key: it.key } : { name: it.name }), path: c.path })
+        if (!it.outdated) toMark[kind === 'nav' ? 'nav' : 'components'].push(it)
+      }
+    }
+  }
+  const out = { platform, repoPath, summary }
+  out.changed = changed.slice(0, LIST_CAP)
+  if (changed.length > LIST_CAP) out.changedTruncated = changed.length - LIST_CAP
+  const stale = [...nav, ...components].filter(i => i.stale).map(i => i.name || i.key)
+  out.stale = stale.slice(0, LIST_CAP)
+  if (stale.length > LIST_CAP) out.staleTruncated = stale.length - LIST_CAP
+  if (record !== false) {
+    let navMarked = 0, compMarked = 0
+    for (const part of chunk(toMark.nav, BATCH_SIZE)) {
+      await io.writeNav(part.map(n => ({ platform, kind: n.kind, name: n.name, key: n.key, outdated: true })))
+      navMarked += part.length
+    }
+    if (toMark.components.length) {
+      const cats = await io.fetchCategories()
+      for (const part of chunk(toMark.components, BATCH_SIZE)) {
+        await io.writeComponents(part.map(c => ({ name: c.name, category: cats.get(c.name) || 'other', platforms: [{ platform, outdated: true }] })))
+        compMarked += part.length
+      }
+    }
+    out.markedOutdated = { nav: navMarked, components: compMarked }
+  } else {
+    out.markedOutdated = { nav: 0, components: 0, note: 'record:false, no se escribió nada' }
+  }
+  return out
+}
+
+export async function runMark({ platform, repoPath, nav, components, all }, io) {
+  const navKeys = arr(nav), compNames = arr(components)
+  if (!all && !navKeys.length && !compNames.length) {
+    throw new Error('Indica qué marcar: all:true (línea base de todo lo que tenga sourceRef), nav (keys) o components (nombres).')
+  }
+  const data = await io.fetchSync()
+  const navItems = arr(data?.nav), compItems = arr(data?.components)
+  const unresolved = []
+  const pick = (items, wanted, idOf, kind) => {
+    if (all) return items.filter(i => extractSourcePath(i.sourceRef) || (unresolved.push({ kind, [idOf]: i[idOf], reason: 'sin-ruta' }), false))
+    const out = []
+    for (const w of wanted) {
+      const it = items.find(i => i[idOf] === w)
+      if (!it) unresolved.push({ kind, [idOf]: w, reason: 'no-encontrado' })
+      else out.push(it)
+    }
+    return out
+  }
+  const navSel = pick(navItems, navKeys, 'key', 'nav')
+  const compSel = pick(compItems, compNames, 'name', 'component')
+  const cache = new Map()
+  const resolve = (it, kind, idOf) => {
+    const c = classifyItem(it, repoPath, cache)
+    if (!c.hash) { unresolved.push({ kind, [idOf]: it[idOf], reason: c.state }); return null }
+    return c.hash
+  }
+  const navW = [], compW = []
+  for (const it of navSel) { const h = resolve(it, 'nav', 'key'); if (h) navW.push({ platform, kind: it.kind, name: it.name, key: it.key, sourceHash: h }) }
+  const compPairs = []
+  for (const it of compSel) { const h = resolve(it, 'component', 'name'); if (h) compPairs.push({ name: it.name, h }) }
+  for (const part of chunk(navW, BATCH_SIZE)) await io.writeNav(part)
+  if (compPairs.length) {
+    const cats = await io.fetchCategories()
+    for (const p of compPairs) compW.push({ name: p.name, category: cats.get(p.name) || 'other', platforms: [{ platform, sourceHash: p.h }] })
+    for (const part of chunk(compW, BATCH_SIZE)) await io.writeComponents(part)
+  }
+  const out = { platform, repoPath, marked: { nav: navW.length, components: compW.length }, unresolved: unresolved.slice(0, LIST_CAP) }
+  if (unresolved.length > LIST_CAP) out.unresolvedTruncated = unresolved.length - LIST_CAP
+  return out
+}

package/src/server.mjs

@@ -13,6 +13,8 @@ import { SKILLS_CATALOG } from './skillsCatalog.mjs'
 import { parseSource, previewSkill, installSkill } from './skillInstall.mjs'
 import { normalizeStatuses, findClosePath } from './closePath.mjs'
 import { TOOL_GUIDES, GUIDE_TOPICS } from './toolGuides.mjs'
+import { runCheck, runMark } from './designSync.mjs'
+import { getDesignFlow, computeDesignStatus, DESIGN_PLATFORM_ARGS, DESIGN_PLATFORMS } from './designFlow.mjs'
 
 // Versión leída de package.json (3 sep 2026) -- antes estaba hardcodeada
 // aquí y quedaba atrás en cada bump (decía 1.16.0 con package.json en 1.16.2).
@@ -3275,6 +3277,111 @@ export function createServer() {
   )
 
   // ═══ PARIDAD DE DISEÑO (ORQ-563) ═══════════════════════════════════════════
+
+  // ═══ FLUJO GUIADO DE DISEÑO (ORQ-564) ══════════════════════════════════════
+  server.registerTool(
+    'get_design_flow',
+    {
+      description: 'Guía paso a paso para llenar Diseño / UI (tokens, navegación, bloques, acciones, componentes, paridad, deriva). Datos estáticos, sin red. Con platform devuelve además un agentPrompt listo para pegar; con step, solo ese paso. Empieza por get_design_status.',
+      inputSchema: {
+        platform: z.enum(DESIGN_PLATFORM_ARGS).optional().describe('web | ios | android | all (default all)'),
+        step: z.string().optional().describe('Id de un paso (check, identity, navigation, blocks, actions-states, components, parity, drift, screenshots)'),
+      },
+    },
+    async ({ platform, step }) => {
+      const data = getDesignFlow({ platform, step })
+      if (data.error) return { content: [{ type: 'text', text: data.error }], isError: true }
+      return textResult(data)
+    }
+  )
+
+  server.registerTool(
+    'get_design_status',
+    {
+      description: 'Estado de Diseño / UI por plataforma (web, ios, android): tokens, nodos de navegación, pantallas con bloques/acciones/estados, componentes, deriva abierta, sync con el código y resumen de paridad, más `next`: el primer paso de get_design_flow pendiente. Solo números, sin listas.',
+      inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC) },
+    },
+    async ({ projectId }) => {
+      try {
+        const pid = resolveProjectId(projectId)
+        const safe = p => p.catch(e => ({ __error: e instanceof ApiError ? `HTTP ${e.status}: ${e.message}` : e.message }))
+        const [tokens, components, drift, parity, ...rest] = await Promise.all([
+          safe(apiGet(config, '/v1/design-tokens', { projectId: pid })),
+          safe(apiGet(config, '/v1/design-components', { projectId: pid })),
+          safe(apiGet(config, '/v1/design-drift', { projectId: pid })),
+          safe(apiGet(config, '/v1/design-parity', { projectId: pid })),
+          ...DESIGN_PLATFORMS.map(platform => safe(apiGet(config, '/v1/design-nav', { projectId: pid, platform }))),
+          ...DESIGN_PLATFORMS.map(platform => safe(apiGet(config, '/v1/design-sync', { projectId: pid, platform }))),
+        ])
+        const n = DESIGN_PLATFORMS.length
+        const nav = Object.fromEntries(DESIGN_PLATFORMS.map((pl, i) => [pl, rest[i]]))
+        const sync = Object.fromEntries(DESIGN_PLATFORMS.map((pl, i) => [pl, rest[n + i]]))
+        return textResult(computeDesignStatus({ tokens, components, drift, parity, nav, sync }))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  // ═══ SINCRONÍA CON EL CÓDIGO (ORQ-575) ═════════════════════════════════════
+  const designSyncIo = (pid, platform, staleDays) => ({
+    fetchSync: () => apiGet(config, '/v1/design-sync', { projectId: pid, platform, staleDays }),
+    fetchCategories: async () => {
+      const r = await apiGet(config, '/v1/design-components', { projectId: pid })
+      const list = Array.isArray(r) ? r : Array.isArray(r?.items) ? r.items : []
+      return new Map(list.filter(c => c?.name && c.category).map(c => [c.name, c.category]))
+    },
+    writeNav: nodes => apiPost(config, '/v1/design-nav/bulk', { projectId: pid, nodes, compact: true }),
+    writeComponents: components => apiPost(config, '/v1/design-components/bulk', { projectId: pid, components, compact: true }),
+  })
+  const SYNC_PLATFORM = z.enum(['web', 'ios', 'android']).describe('web | ios | android')
+  const SYNC_REPO = z.string().min(1).describe('Ruta absoluta del repo de esa plataforma en esta máquina')
+
+  server.registerTool(
+    'check_design_sync',
+    {
+      description: 'Compara el código local con lo cargado en Diseño / UI (sourceRef + huella) y reporta qué cambió; con record (default true) marca lo cambiado como outdated. Solo lee archivos dentro de repoPath. Devuelve conteos y listas cortas.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: SYNC_PLATFORM,
+        repoPath: SYNC_REPO,
+        staleDays: z.number().int().min(1).max(365).optional().describe('Días sin sincronizar para considerar stale (1-365)'),
+        record: z.boolean().optional().describe('false = solo reporta, no marca outdated (default true)'),
+      },
+    },
+    async ({ projectId, platform, repoPath, staleDays, record }) => {
+      try {
+        if (!path.isAbsolute(repoPath)) throw new Error('repoPath debe ser una ruta absoluta')
+        return textResult(await runCheck({ platform, repoPath, record }, designSyncIo(resolveProjectId(projectId), platform, staleDays)))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'mark_design_synced',
+    {
+      description: 'Guarda la huella actual del código como sincronizada (limpia outdated). Úsala solo después de haber actualizado/revisado en Orquestra lo que cambió, o para fijar la línea base tras una carga completa (all:true).',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        platform: SYNC_PLATFORM,
+        repoPath: SYNC_REPO,
+        nav: z.array(z.string()).optional().describe('Keys de nodos de navegación a marcar'),
+        components: z.array(z.string()).optional().describe('Nombres de componentes a marcar'),
+        all: z.boolean().optional().describe('true = línea base de todo lo que tenga sourceRef en la plataforma'),
+      },
+    },
+    async ({ projectId, platform, repoPath, nav, components, all }) => {
+      try {
+        if (!path.isAbsolute(repoPath)) throw new Error('repoPath debe ser una ruta absoluta')
+        return textResult(await runMark({ platform, repoPath, nav, components, all }, designSyncIo(resolveProjectId(projectId), platform)))
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
   const PARITY_PLATFORMS = ['web', 'ios', 'android']
   server.registerTool(
     'get_design_parity',