@iaforged/context-code 1.0.84 → 1.0.86

package/docs/PHASE_1_WORKSPACES_AGENTS_TEAMS.md

@@ -0,0 +1,161 @@
+# Fase 1: workspaces, agents, teams y topologia
+
+Este documento describe la capa organizacional objetivo que se construye encima de la base actual de `provider + profile + SQLite`.
+
+No define comandos nuevos ni cambia el runtime por si solo. Su proposito es fijar el vocabulario y la estructura para que la siguiente evolucion del sistema no mezcle conceptos.
+
+## Resumen ejecutivo
+
+- `workspace` es la unidad organizacional de un proveedor.
+- `profile` es una cuenta o configuracion concreta dentro de ese workspace.
+- `agent` es un rol operativo o subagente dentro de un workspace o perfil.
+- `team` es una agrupacion transversal que coordina varios workspaces.
+- `topologia` es la relacion entre el orquestador global, los teams, los workspaces, los profiles y los agents.
+
+## Lo que ya existe hoy
+
+- `provider profiles` en SQLite.
+- `agentName` reservado como nombre operativo.
+- credenciales de Windows/Linux en SQLite cifrado local.
+- perfiles por proveedor con base URL y ultimo modelo.
+
+Eso significa que la fase organizacional no parte desde cero. Parte sobre una capa de estado ya estable.
+
+## Topologia objetivo
+
+```mermaid
+flowchart TD
+  GO["Global orchestrator"]
+  TM["Team"]
+  WS["Workspace / provider"]
+  PF["Provider profile"]
+  AG["Agent / subagent"]
+
+  GO --> TM
+  TM --> WS
+  WS --> PF
+  PF --> AG
+```
+
+Lectura del diagrama:
+
+- el `Global orchestrator` decide la estrategia general
+- cada `Team` agrupa dominios o lineas de trabajo
+- cada `Workspace` representa un proveedor concreto
+- cada `Profile` representa una cuenta o configuracion dentro del workspace
+- cada `Agent` representa un rol interno, un subagente o una especializacion
+
+## Entidades de la Fase 1
+
+### `provider_workspaces`
+
+Representa al proveedor como unidad organizacional.
+
+Campos tipicos:
+
+- `id`
+- `provider`
+- `display_name`
+- `domain_focus`
+- `is_enabled`
+- `created_at`
+- `updated_at`
+
+### `provider_agents`
+
+Representa subagentes o roles internos.
+
+Campos tipicos:
+
+- `id`
+- `workspace_id`
+- `profile_id`
+- `name`
+- `role_kind`
+- `system_prompt`
+- `model_override`
+- `tool_policy`
+- `autonomy_level`
+- `is_orchestrator`
+- `is_enabled`
+- `created_at`
+- `updated_at`
+
+### `teams`
+
+Representa equipos transversales.
+
+Campos tipicos:
+
+- `id`
+- `name`
+- `description`
+- `global_orchestrator_agent_id`
+- `is_enabled`
+- `created_at`
+- `updated_at`
+
+### `team_domains`
+
+Representa dominios de asignacion dentro de un team.
+
+Campos tipicos:
+
+- `id`
+- `team_id`
+- `domain_name`
+- `workspace_id`
+- `local_orchestrator_agent_id`
+- `lead_agent_id`
+- `selection_mode`
+- `required`
+
+## Regla de separacion
+
+- `provider` no es `profile`
+- `profile` no es `agent`
+- `agent` no es `team`
+- `team` no es `workspace`
+
+La fase 1 existe precisamente para evitar que esos conceptos se vuelvan a mezclar.
+
+## Criterio de cierre de la fase
+
+La fase 1 queda cerrada cuando se pueda:
+
+- definir un workspace por proveedor
+- registrar agentes dentro de ese workspace
+- agrupar workspaces en teams
+- inspeccionar la topologia completa desde la CLI o la UI
+
+## Comandos base de la fase
+
+La fase ya expone una primera capa manual:
+
+- `/workspace`
+- `/workspace show <proveedor>`
+- `/workspace enable <proveedor>`
+- `/workspace disable <proveedor>`
+- `/agent list [proveedor]`
+- `/agent create <proveedor> <name> [profile]`
+- `/agent show <proveedor> <name>`
+- `/agent set-role <proveedor> <name> <role>`
+- `/agent set-orchestrator <proveedor> <name> <true|false>`
+- `/agent set-model <proveedor> <name> <model|clear>`
+- `/team list`
+- `/team create <name>`
+- `/team show <name>`
+- `/team orchestrator <team> <proveedor>/<agente>`
+- `/team domain <team> <domain> <proveedor>/<agente>`
+- `/team add-member <team> <domain> <proveedor>/<agente> [duty]`
+
+## Nota de alcance
+
+Esta fase no incluye todavia:
+
+- ejecucion real de orquestacion
+- reparto automatico de tareas
+- ranking inteligente de agentes
+- trazabilidad de runs
+
+Eso pertenece a fases posteriores.

package/docs/PHASE_2_SQLITE_ORCHESTRATION.md

@@ -0,0 +1,127 @@
+# Fase 2: planning y trazabilidad inicial sobre SQLite
+
+Este documento describe la capa inicial de orquestacion que se monta encima de la topologia de providers, profiles, agents y teams.
+
+La Fase 1 deja la estructura de configuracion y nomenclatura. La Fase 2 usa esa base para registrar decisiones, runs, tareas y mensajes de orquestacion de forma persistente.
+
+## Objetivo
+
+Transformar la definicion de equipos en una topologia planeable:
+
+- provider workspace
+- provider profile
+- provider agent
+- team
+- domain
+- member
+- run
+- task
+- message
+
+La meta es que SQLite sea la fuente de verdad para el planning y la trazabilidad inicial, mientras que los comandos de Fase 1 siguen sirviendo como superficie de configuracion.
+
+## Base de almacenamiento
+
+La orquestacion inicial se apoya en la base SQLite de Context Code:
+
+- `~/.context/provider-state.sqlite3`
+
+Tablas relevantes:
+
+- `provider_workspaces`
+- `provider_profiles`
+- `provider_agents`
+- `teams`
+- `team_domains`
+- `team_domain_members`
+- `orchestration_runs`
+- `orchestration_tasks`
+- `orchestration_messages`
+
+## Flujo inicial de planning
+
+El flujo recomendado para montar una corrida planeada es:
+
+1. configurar el proveedor y el perfil activo
+2. crear un team
+3. asignar un orchestrator para el team
+4. declarar dominios de trabajo
+5. agregar miembros por dominio
+6. inspeccionar la topologia
+7. crear la corrida inicial sobre SQLite
+
+En la practica:
+
+```sh
+/provider <proveedor> profile <perfil>
+/profile use <proveedor> <perfil>
+
+/team create <name>
+/team orchestrator <team> <provider>/<agent>
+/team domain <team> <domain> <provider>/<agent>
+/team add-member <team> <domain> <provider>/<agent> [duty]
+
+/team list
+/team show <name>
+
+/orchestrate <team> <objetivo>
+```
+
+## Estados de tarea
+
+La Fase 2 usa estados simples para que la inspeccion sea rapida:
+
+- `ready`: la tarea quedo lista para ejecutarse
+- `blocked`: falta una dependencia, un dominio o una asignacion valida
+
+## Como inspeccionar una corrida
+
+La corrida se revisa desde la CLI con `/run`:
+
+- `/run list` muestra los identificadores disponibles
+- `/run show <run-id>` muestra el detalle completo de una corrida
+- `/run tasks <run-id>` muestra tareas por dominio
+- `/run messages <run-id>` muestra la bitacora persistida
+- el detalle debe incluir el team, el objetivo, el orchestrator global y las tareas por dominio
+- cada tarea debe mostrar su estado, de forma que se entienda si quedo `ready` o `blocked`
+
+## Limites de Fase 2
+
+La Fase 2 no intenta resolver todo el trabajo de forma automatica. En este punto:
+
+- no ejecuta subagentes reales automaticamente
+- no hace consolidacion final por dominio
+- no reemplaza el flujo manual de `/team`, `/workspace` y `/agent`
+- no introduce subdelegacion profunda dentro de cada squad
+- deja el run preparado para que Fase 3 pueda arrancar ejecucion por dominio
+
+## Comandos de Fase 1 que alimentan Fase 2
+
+Los comandos de `team` no ejecutan la orquestacion completa por si solos. Sirven para dejar lista la topologia que la capa de orquestacion consumira:
+
+- `/team list`
+- `/team create <name>`
+- `/team show <name>`
+- `/team orchestrator <team> <provider>/<agent>`
+- `/team domain <team> <domain> <provider>/<agent>`
+- `/team add-member <team> <domain> <provider>/<agent> [duty]`
+
+## Criterio de cierre
+
+La fase queda bien definida cuando se pueda:
+
+- guardar la topologia del equipo
+- leer el team completo desde SQLite
+- registrar runs y tareas de orquestacion
+- asignar dominios y miembros sin mezclar provider, profile y agent
+- inspeccionar runs, tareas y mensajes sin depender de estado en memoria
+
+## Relacion con otras fases
+
+La Fase 1 define la estructura. La Fase 2 usa esa estructura para planear y trazar trabajo distribuido.
+
+En otras palabras:
+
+- Fase 1 = configuracion y topologia
+- Fase 2 = planning persistido y trazabilidad sobre SQLite
+- Fase 3 = ejecucion real por dominio y reporte consolidado

package/docs/PHASE_3_DOMAIN_EXECUTION.md

@@ -0,0 +1,215 @@
+# Fase 3: ejecucion por dominio y reporte consolidado
+
+Este documento describe la Fase 3 del sistema multi-squad de Context Code.
+
+La Fase 2 crea runs, tareas y mensajes sobre SQLite. La Fase 3 toma esas corridas y las convierte en ejecucion real por dominio, con reportes de escuadron hacia el orquestador global.
+
+## Objetivo
+
+Ejecutar trabajo distribuido con dos niveles de coordinacion:
+
+- `orquestador global`: coordina el objetivo completo y consolida resultados
+- `orquestador local`: lidera un dominio o escuadron concreto
+- `miembros del dominio`: ejecutan tareas especializadas dentro del escuadron
+- `SQLite`: guarda el estado de runs, tasks, messages, resultados de tarea y reportes consolidados
+
+La meta no es que todos los agentes sean autonomos desde el primer dia. La meta es que cada dominio pueda avanzar, reportar y dejar trazabilidad consistente.
+
+## Flujo de ejecucion
+
+El flujo esperado para una corrida de Fase 3 es:
+
+1. El usuario crea o arranca una corrida.
+2. El orquestador global carga el team y sus dominios desde SQLite.
+3. Cada dominio recibe una tarea con agente asignado.
+4. El dominio pasa de `ready` a `in_progress`.
+5. El runtime resuelve `agente -> workspace -> perfil -> modelo -> credenciales`.
+6. El dominio termina como `completed`, `failed` o `blocked`.
+7. El orquestador global consolida los reportes de todos los dominios.
+8. La corrida termina como `completed`, `failed`, `cancelled` o queda lista para `resume`.
+
+## Comandos principales
+
+### Crear y arrancar una corrida
+
+```sh
+/run start <team> <goal>
+```
+
+Este comando debe:
+
+- crear la corrida si todavia no existe
+- mover la corrida a estado de ejecucion
+- registrar mensajes de inicio
+- servir para corridas directas; el flujo multi-dominio recomendado sigue siendo `/orchestrate <team> <goal>` y luego `/run resume <run-id>`
+
+Ejemplo:
+
+```sh
+/run start core-dev crear login con UI y API
+```
+
+### Reanudar una corrida
+
+```sh
+/run resume <run-id>
+```
+
+Este comando debe:
+
+- cargar una corrida existente
+- saltar tareas ya completadas
+- procesar tareas `ready`, `blocked` recuperables o `in_progress` que puedan continuar
+- registrar mensajes nuevos sin borrar la bitacora anterior
+- actualizar el estado final de la corrida segun el resultado de sus dominios
+
+### Cancelar una corrida
+
+```sh
+/run cancel <run-id>
+```
+
+Este comando debe:
+
+- marcar la corrida como `cancelled`
+- cancelar tareas pendientes cuando aplique
+- registrar un mensaje de cancelacion
+- evitar que `resume` siga ejecutando trabajo activo sin una decision explicita
+
+### Ver tareas por dominio
+
+```sh
+/run tasks <run-id>
+/run task <task-id>
+/run domain <run-id> <domain>
+```
+
+Este comando debe mostrar:
+
+- dominio
+- agente asignado
+- estado de tarea
+- resumen de salida
+- bloqueo o error si existe
+- marca de tiempo relevante
+
+### Operaciones manuales de recuperacion
+
+```sh
+/run retry <run-id> [task-id]
+/run cancel-task <task-id>
+/run reassign <task-id> <provider>/<agent>
+```
+
+Estos comandos permiten reintentar, bloquear o reasignar trabajo sin borrar trazabilidad.
+
+### Ver mensajes de la corrida
+
+```sh
+/run messages <run-id>
+```
+
+Este comando debe mostrar la bitacora persistida:
+
+- mensajes del orquestador global
+- reportes de escuadron
+- errores
+- decisiones de planning
+- cambios relevantes de estado
+
+## Estados de corrida
+
+Los estados esperados son:
+
+- `planned`: la corrida existe, pero todavia no ejecuto dominios
+- `in_progress`: la corrida esta procesando dominios
+- `completed`: todos los dominios terminaron correctamente o con resultado aceptado
+- `failed`: la corrida fallo por un error no recuperable
+- `cancelled`: el usuario cancelo la corrida
+
+## Estados de tarea
+
+Los estados esperados son:
+
+- `ready`: la tarea esta preparada para ejecutar
+- `in_progress`: el dominio esta trabajando
+- `completed`: el dominio reporto resultado
+- `failed`: el dominio fallo durante la ejecucion
+- `blocked`: falta configuracion, agente, credencial o dependencia
+- cuando la corrida se cancela, las tareas abiertas quedan bloqueadas o conservan su estado terminal previo
+
+## Reporte de escuadron
+
+Cada escuadron debe reportar al orquestador global con una estructura minima:
+
+- `domain`: dominio ejecutado
+- `lead`: agente responsable del dominio
+- `status`: estado final del dominio
+- `summary`: resumen de lo realizado
+- `artifacts`: archivos, decisiones o resultados relevantes
+- `blockers`: bloqueos encontrados
+- `nextAction`: siguiente accion recomendada
+
+Ese reporte queda persistido en tres niveles:
+
+- `orchestration_messages`: bitacora cronologica de dispatch, bloqueo y reporte.
+- `orchestration_task_results`: salida estructurada por tarea/agente.
+- `orchestration_domain_reports`: resumen actual del dominio para el orquestador global.
+
+La tarea correspondiente en `orchestration_tasks` tambien conserva `result_summary` para lectura rapida.
+
+## Reporte consolidado global
+
+El orquestador global debe consolidar:
+
+- estado general de la corrida
+- dominios completados
+- dominios bloqueados
+- dominios fallidos
+- resumen ejecutivo
+- riesgos pendientes
+- recomendacion de continuar, reintentar, reasignar o cerrar
+
+La consolidacion no reemplaza los mensajes. Los mensajes son la bitacora completa; el consolidado se guarda en `orchestration_run_reports` como lectura operativa para decidir el siguiente paso.
+
+## Limites actuales
+
+Fase 3 debe mantener estos limites claros:
+
+- la ejecucion por dominio sigue siendo guiada por comandos mientras se estabiliza el runtime
+- la llamada real al proveedor ocurre cuando el agente tiene workspace, perfil, modelo y credenciales validas
+- la subdelegacion profunda dentro de cada escuadron puede empezar como reporte del lead local
+- si un dominio no tiene agente, perfil, credencial o modelo valido, debe quedar `blocked`
+- los errores de proveedor no deben reintentarse indefinidamente si son de cuota, autenticacion o modelo invalido
+- el usuario debe poder inspeccionar y retomar sin perder trazabilidad
+
+## Criterio de cierre de Fase 3
+
+Fase 3 queda cerrada cuando:
+
+- `/run start` crea o arranca una corrida operativa
+- `/run resume` continua una corrida existente
+- `/run cancel` detiene una corrida de forma persistente
+- `/run tasks` muestra el estado por dominio
+- `/run task` y `/run domain` muestran detalle operativo y resultados persistidos
+- `/run retry`, `/run cancel-task` y `/run reassign` permiten recuperacion manual segura
+- `/run messages` muestra la bitacora
+- cada dominio produce un reporte hacia el orquestador global
+- el orquestador global produce un consolidado
+- los resultados quedan persistidos en `orchestration_task_results`, `orchestration_domain_reports` y `orchestration_run_reports`
+- los estados de runs y tasks sobreviven reinicios de la app
+
+## Arranque de Fase 4
+
+Cuando Fase 3 este estable, Fase 4 debe agregar autonomia y optimizacion:
+
+- seleccion automatica de agentes por capacidades
+- ranking por costo, latencia y calidad
+- fallback entre proveedores cuando un escuadron falle
+- reasignacion automatica de dominios bloqueados
+- politicas de retry por tipo de error
+- autocompletado de teams, agents, dominios y run ids
+- metricas por escuadron y proveedor
+- tests de integracion para runs, tasks, messages y reportes
+
+Fase 4 no debe borrar la estructura manual. La configuracion manual debe seguir existiendo como modo explicito y auditable.

package/docs/PHASE_3_VALIDATION.md

@@ -0,0 +1,136 @@
+# Fase 3: validacion de ejecucion por dominio
+
+Este documento fija la validacion tecnica actual para la Fase 3 de orquestacion. El repo no tiene un harness unitario propio configurado en `package.json`; por ahora el gate automatizable y reproducible es build, mas pruebas manuales sobre los comandos que escriben en SQLite.
+
+## Alcance validado
+
+La Fase 3 cubre:
+
+- ciclo operativo de corrida desde `/run`
+- cambio de estados de `orchestration_runs`
+- cambio de estados de `orchestration_tasks`
+- mensajes persistidos en `orchestration_messages`
+- reporte consolidado por escuadron desde `/run show` y `/run report`
+- inspeccion detallada con `/run tasks` y `/run messages`
+- inspeccion puntual con `/run task <task-id>` y `/run domain <run-id> <domain>`
+- operaciones manuales seguras con `/run retry`, `/run cancel-task` y `/run reassign`
+
+## Verificaciones automatizables disponibles
+
+Ejecutar:
+
+```sh
+npm run build
+```
+
+Resultado esperado:
+
+- `tsc -p tsconfig.json` compila.
+- `scripts/postprocess-build.mjs` termina con `Build postprocess completed.`
+
+Tambien se puede ejecutar:
+
+```sh
+npm run typecheck
+```
+
+Estado actual:
+
+- no es gate de Fase 3 todavia.
+- falla por deuda global previa en bridge, plugins, secure storage legacy, mensajes SDK y otros modulos fuera del runtime de orquestacion.
+- si se limpia esa deuda, este comando debe pasar a ser gate obligatorio.
+
+## Flujo manual recomendado
+
+Preparar topologia minima:
+
+```text
+/provider claude profile main
+/agent create claude frontend-lead main
+/agent set-orchestrator claude frontend-lead true
+
+/provider openai profile work
+/agent create openai backend-lead work
+
+/team create core-dev
+/team orchestrator core-dev claude/frontend-lead
+/team domain core-dev frontend claude/frontend-lead
+/team domain core-dev backend openai/backend-lead
+/team show core-dev
+```
+
+Crear y revisar planning:
+
+```text
+/orchestrate core-dev crear login con UI y API
+/run list
+/run show <run-id>
+/run tasks <run-id>
+/run messages <run-id>
+/run domain <run-id> frontend
+```
+
+Ejecutar Fase 3:
+
+```text
+/run resume <run-id>
+/run show <run-id>
+/run tasks <run-id>
+/run messages <run-id>
+/run task <task-id>
+```
+
+Cancelar o reiniciar escenarios:
+
+```text
+/run cancel <run-id>
+/run resume <run-id>
+/run retry <run-id>
+/run retry <run-id> <task-id>
+/run cancel-task <task-id>
+/run reassign <task-id> claude/frontend-lead
+```
+
+## Estados esperados
+
+Corridas:
+
+- `planned`: creada, sin ejecucion.
+- `in_progress`: ejecucion por dominio en curso.
+- `completed`: todos los dominios ejecutables reportaron resultado.
+- `failed`: hay dominios bloqueados o fallidos.
+- `cancelled`: detenida por el usuario.
+
+Tareas:
+
+- `pending`: creada pero no lista.
+- `ready`: lista para ejecucion.
+- `in_progress`: asignada a un agente de dominio.
+- `completed`: reporto resultado.
+- `failed`: fallo durante ejecucion.
+- `blocked`: falta agente, workspace, credencial o configuracion.
+
+## Casos que deben cubrirse antes de cerrar Fase 3
+
+- `/run resume <run-id>` cambia tareas `ready` a `completed` cuando tienen agente valido.
+- `/run resume <run-id>` marca `blocked` si el agente asignado no existe.
+- `/run cancel <run-id>` marca la corrida `cancelled` y bloquea tareas abiertas.
+- `/run messages <run-id>` muestra `task.dispatch`, `squad.report` y `global.consolidated-report`.
+- `/run show <run-id>` consolida por dominio y muestra el orquestador local o lead asignado.
+- una corrida con dominios incompletos no debe reportarse como `completed`.
+- `/run task <task-id>` muestra estado, agente, dominio, mensajes y resultados persistidos.
+- `/run domain <run-id> <domain>` filtra tareas, mensajes y resultados por dominio.
+- `/run retry <run-id>` mueve tareas `failed` o `blocked` a `ready` si tienen agente asignado.
+- `/run retry <run-id> <task-id>` reintenta solo una tarea de esa corrida.
+- `/run cancel-task <task-id>` detiene la tarea como `blocked` porque el modelo de estados no tiene `cancelled` por tarea.
+- `/run reassign <task-id> <provider>/<agent>` cambia el agente asignado y deja la tarea `ready` si no estaba completada.
+
+## Recomendacion de harness futuro
+
+Cuando el repo tenga un harness unitario formal, las primeras pruebas deberian cubrir:
+
+- `runStore`: crear/listar/actualizar runs, tasks, messages y reports.
+- `OrchestrationExecutionRuntime`: transiciones validas e invalidas.
+- comandos `/run`: parseo de argumentos, fallback y salida de errores.
+- comandos `/orchestrate`: creacion de tareas `ready` y `blocked`.
+- persistencia SQLite: reinicio de proceso y recuperacion de estado.