Beans y tareas
TR
En esta página
Esta página se genera a partir de content/docs/beans-and-todos/ — cada sección a continuación enlaza a su propia fuente.
✎ Edit TR
Los beans son para los agentes. Las tareas (todos) son para los humanos. Comparten una misma palabra en el habla cotidiana y nada más, y confundirlas es como un plan de trabajo llega a albergar dos clases de cosas que necesitan un tratamiento distinto.
Un bean es el estado de proceso que un agente conserva mientras realiza trabajo: reclamado
antes de comenzar para que una sesión hermana lo evite, mantenido al día a medida que el trabajo avanza
y cerrado con un registro de lo que cambió. El almacén es beans/, guardado en el repositorio (committed),
por lo que sobrevive a la recuperación de un contenedor y es visible para cualquier otra sesión.
Una tarea (todo) es el recordatorio propio de una persona: lo que tiene intención de mirar a continuación. Es suyo para crearlo, reordenarlo y descartarlo según su propio calendario y ningún otro, y nada en el proceso de un agente debería decidir cuándo está terminado.
Esta página describe lo primero en su totalidad. Lo segundo aún no está construido y así lo declara.
Dos cosas que comparten una palabra
✎ Edit TR
La distinción no es una cuestión terminológica. Los dos tienen diferentes propietarios, diferentes ciclos de vida y diferentes modos de fallo.
| Bean | Todo (tarea) | |
|---|---|---|
| Propietario | Una sesión de agente | Una persona |
| Propósito | Estado de proceso para trabajo en curso | Un recordatorio de intención |
| Almacén | beans/, en el repositorio y compartido | Aún no definido |
| Creado por | Un agente, tras una comprobación de título exacto | La persona, cuando lo desee |
| Cerrado por | El agente que realizó el trabajo, con un resumen | La persona, a su propio juicio |
| Visible para | Toda sesión hermana | La persona, principalmente |
| Modo de fallo | Duplicado, o cerrado por la sesión equivocada | Olvidado |
Los modos de fallo son los que hacen que valga la pena mantener la separación. Un bean duplicado priva de señal al plan de trabajo —en un folio, una reejecución sin protecciones produjo 14.688 duplicados, el 92 % de cada bean abierto en el repositorio. Un todo olvidado incomoda a una persona. La maquinaria dimensionada para lo primero resulta excesivamente ceremoniosa en lo segundo, y la maquinaria dimensionada para lo segundo se queda lejísimos de ser suficiente para lo primero.
El ciclo de vida del bean de agente
✎ Edit TR
El diagrama anterior muestra el ciclo completo, y tres de sus aristas son las que vale la pena leer dos veces.
El primer paso es una búsqueda, no una creación. beans create no es
idempotente: genera un identificador nuevo en cada llamada y no deduplica nada,
por lo que volver a entrar en un paso duplica el plan en lugar de no hacer nada.
La comprobación por título exacto es lo que se interpone entre un paso repetido del flujo
de trabajo y un corpus de beans casi idénticos.
La propiedad es una compuerta, no una cortesía. Un bean que otra sesión reclamó no te corresponde resolverlo, descartarlo ni eliminarlo. Reclamar es la forma en que dos sesiones evitan tomar el mismo elemento; cerrar el de otra persona o sesión es cómo una de ellas pierde trabajo que aún no había terminado de reportar.
«Bloqueado» no es «no deseado». Un bean bloqueado vuelve a todo con su
bloqueador registrado y una indicación de qué lo resolvería. Dejarlo en
in-progress es peor que cualquiera de las dos cosas: un elemento en el que nadie está avanzando se lee,
para cualquier otra sesión, como trabajo activo.
Un bean nunca se elimina
✎ Edit TR
beans delete existe en la CLI. No lo uses.
El trabajo que resulta no ser necesario se descarta (scrapped) — status: scrapped,
con una sección que explica por qué. Eso es lo que significa «deshabilitar» aquí; la CLI no tiene un
estado deshabilitado, y su vocabulario es draft, todo, in-progress,
completed, scrapped.
El motivo no es el orden. Un bean descartado registra que algo fue considerado y rechazado, y sobre qué bases —lo cual vale tanto para el siguiente agente como el registro del trabajo que sí se hizo, porque es lo que evita que se vuelva a entrar en el mismo callejón sin salida. Un bean eliminado deja a una sesión hermana sin posibilidad de distinguir el abandono intencional de un accidente, y deja al siguiente agente en libertad de volver a empezar en lo que tú ya habías descartado.
La prohibición está escrita aquí, y en la propia documentación del diagrama, precisamente porque la herramienta ofrece la operación. Una regla que depende de que nadie se percate de un comando no es una regla.
Las operaciones del motor no son llamadas a la CLI
✎ Edit TR
Dos entidades diferentes pueden modificar un bean, y un paso que las confunda anunciará un efecto que en realidad no produce.
El motor de flujos de trabajo ejecuta claim, note y resolve sobre el bean
propio de una instancia de proceso cuando se completa un paso marcado con <cat-harness.processes:bean op="…"/>.
claim establece in-progress y es idempotente; note añade contenido al final; resolve
completa el bean únicamente una vez que la propia instancia se ha completado, porque
determinar si el trabajo está terminado es un juicio y un bean no se cierra por el mero dicho
de un tercero.
El agente realiza todo lo demás con la CLI de beans: crear, descartar,
cambiar de título, establecer un bloqueador. El motor no tiene ninguna operación para nada de esto.
Esta no es una distinción hipotética. Una actividad en el diagrama de CRDM
incluía <cat-harness.processes:bean action="create"/> —action, donde el motor lee
op— por lo que se interpretó como ninguna operación en absoluto. El paso anunciaba que la firma
producía beans, no ejecutaba nada, y lo hacía silenciosamente hasta que alguien leyó el
analizador (parser).
Cuando añadas un paso marcado con bean, utiliza una de las tres operaciones que el
motor implementa, e indica en la documentación del paso qué partes son llamadas a la CLI
propias del agente. bun run cat check:workflow-refs detectará una referencia de habilidad
que no se resuelva; pero no puede detectar un atributo plausible que el
motor nunca lee.
Tareas humanas (todos) — aún no construido
✎ Edit TR
Aún no construido, y expresado aquí en lugar de dejarlo como una ausencia que alguien tenga que advertir.
Las tareas de una persona necesitan un ciclo propio, y nada de eso existe todavía:
- Cuándo se muestra una tarea. Mostrar cada elemento abierto en cada turno es ruido; no mostrar ninguno produce una lista que nadie lee. Sea cual sea la regla, no es la misma que la preparación inicial del plan de trabajo (priming) que un agente recibe al iniciar sesión.
- Cuándo puede una persona crear una, y mediante qué vía —chat, un comando o la superficie de inicio de sesión.
- Cómo se retira una. Que una persona abandone un recordatorio es algo ordinario y no necesita una sección de «motivos para descartar»; las reglas de los beans no se trasladan aquí.
Hasta que eso esté diseñado, no reutilices beans para ello. Un almacén cuyas entradas son reclamadas por sesiones, cerradas con resúmenes de cambios y nunca eliminadas tiene la forma equivocada para un recordatorio que alguien desea abandonar sin ceremonia —y mezclar los dos colocaría elementos en el plan de trabajo del agente sobre los cuales ningún agente debería estar actuando.
Qué contiene el plan de trabajo en este momento
✎ Edit QA TR
El resto de esta página explica lo que un bean es. Esta sección explica lo que el
almacén actualmente contiene —leído en vivo desde
/assets/beans/index.json, la proyección que
gen-docs-pages.ts escribe a partir de beans/defs/ en cada compilación, junto al índice
de tareas (todos) que ha publicado desde hace más tiempo.
Hasta el 2026-09-20 no había nada que poner aquí. todos/ contaba con un lector, un
índice publicado y un panel sobre él; beans/ no tenía ninguno de los tres, a pesar de que
es el almacén mayor por dos órdenes de magnitud. Un plan de trabajo que nadie puede mirar
es uno que nadie revisa.
Qué muestra el panel y por qué cada bloque tiene la forma que tiene. Los recuentos son un encabezado, por lo que son números en lugar de un gráfico de cuatro barras que dicen lo mismo. La distribución por épicas representa la magnitud a través de identidades con nombres largos, por lo que es una barra horizontal. Los hallazgos ocupan tres o cuatro filas, por lo que son una lista —con un icono y una etiqueta en cada fila, porque un color de estado nunca transmite significado por sí solo.
Los hallazgos se calculan únicamente a partir de datos guardados en el repositorio (committed), y uno de ellos falta
a propósito. Un detector de elementos in-progress obsoletos tendría que consultar el
reloj, y la proyección está condicionada a un contenido exacto —cualquier cosa calculada
contra el reloj cambia el archivo en cada compilación y la comprobación de obsolescencia se dispara
indefinidamente. De modo que la proyección publica el updated_at de cada bean como un hecho
y la página calcula la antigüedad al abrirla. La antigüedad, por tanto, avanza sin que el
archivo cambie, lo cual es el sentido correcto.
Existe una vista más completa, y es navegable. Cada grafo de estados declarado
obtiene su propio visualizador en la ruta que esta instancia ya utiliza para dicho grafo —
/beans/, /todos/, y uno para cada uno de los demás. La
ruta no es un invento de esta página: el bean o7eq contiene la decisión del propietario de que
un recurso renderizado se direcciona mediante el nombre de su instancia con el grafo
declarado como un segmento de ruta, y que esta instancia omite su propio nombre porque
su docs/ es lo que sirve el sitio, y la habilidad harness-requirements
especifica esa URL exacta como la obligación —«un requisito de ellos es proporcionar
visualizadores accesibles en <base-url>/beans». No existe un índice general sobre ellos,
porque / corresponde al sitio de documentación, por lo que cada página lista a sus hermanas.
Un grafo sin proyección así lo indica. qa, health, issue-marks y
uploads son grafos de estados declarados para los cuales todavía nada publica una proyección.
Sus paneles indican exactamente eso y mencionan el bean 2krx, en lugar de
mostrar ceros para un almacén que nadie ha leído —un panel que abre en cero es
indistinguible de un almacén sin nada dentro, y esos son hechos
opuestos.
Cada identificador en esas páginas es un enlace. El identificador de un bean se resuelve al archivo del bean, un número de issue o pull request a la forja, y cada hallazgo lleva un lápiz hacia el lugar donde realmente se escribe. Una referencia que no puede resolverse permanece como texto plano, lo que constituye la diferencia visible entre «sigue esto» y «esto apunta a un lugar al que no pude acceder».
Lo que no está aquí. En qué punto de un proceso BPMN se sitúa un bean, lo cual es la otra
mitad del bean v49e. Dicha unión necesita beans/workflows/, el grafo declarado
workflow-state, y se encuentra vacío —por lo que una vista de posición reportaría
«en ningún lugar» para cada bean del almacén. Espera a que el estado de instancias exista.
El panel en vivo del plan de trabajo requiere JavaScript. La proyección que lee es un archivo JSON sin formato y se puede leer directamente.