Beans et tâches
TR
Sur cette page
Cette page est générée à partir de content/docs/beans-and-todos/ — chaque section ci-dessous renvoie vers sa propre source.
✎ Edit TR
Les beans sont pour les agents. Les tâches sont pour les humains. Ils ne partagent qu’un mot dans le langage ordinaire et rien d’autre, et les confondre est la raison pour laquelle un plan de travail en vient à contenir deux types de choses qui nécessitent des traitements différents.
Un bean est un état de processus qu’un agent conserve pendant qu’il effectue son travail : réservé avant de commencer pour qu’une session voisine l’évite, tenu à jour au fur et à mesure que le travail progresse, et clôturé avec un compte-rendu de ce qui a changé. Le stockage s’effectue dans beans/, commité, de sorte qu’il survit à la récupération d’un conteneur et reste visible par toutes les autres sessions.
Une tâche (todo) est le propre pense-bête d’une personne — ce qu’elle a l’intention d’examiner ensuite. Il lui appartient de la créer, de la réorganiser et de l’abandonner selon son propre rythme, et rien dans le processus d’un agent ne devrait décider du moment où elle est terminée.
Cette page décrit le premier en détail. Les secondes ne sont pas encore construites et cette page le dit explicitement.
Deux choses qui partagent un même mot
✎ Edit TR
La distinction n’est pas une simple question de terminologie. Les deux ont des propriétaires différents, des cycles de vie différents et des modes d’échec différents.
| Bean | Tâche (todo) | |
|---|---|---|
| Propriétaire | Une session d’agent | Une personne |
| Objectif | État de processus pour le travail en cours | Un rappel d’intention |
| Stockage | beans/, commité et partagé | Pas encore défini |
| Créé par | Un agent, après vérification du titre exact | La personne, quand elle le souhaite |
| Clôturé par | L’agent qui a effectué le travail, avec un résumé | La personne, selon son propre jugement |
| Visible par | Toutes les sessions voisines | La personne, principalement |
| Mode d’échec | Dupliqué, ou clôturé par la mauvaise session | Oublié |
Ce sont les modes d’échec qui justifient de maintenir cette séparation. Un bean dupliqué prive le plan de travail de tout signal utile — dans un folio, une réexécution sans garde-fou a produit 14 688 doublons, soit 92 % de tous les beans ouverts du dépôt. Une tâche oubliée ne gêne qu’une seule personne. Un mécanisme dimensionné pour le premier relève de la cérémonie inutile pour la seconde, et un mécanisme dimensionné pour la seconde est très loin de suffire pour le premier.
Le cycle de vie des beans d’agent
✎ Edit TR
Le diagramme ci-dessus représente l’intégralité du cycle, et trois de ses transitions méritent d’être lues à deux fois.
La première étape est une recherche, pas une création. beans create n’est pas idempotent : il génère un nouvel identifiant à chaque appel et n’élimine aucun doublon, de sorte que réexécuter une étape duplique le plan au lieu de ne rien faire. La vérification du titre exact est ce qui sépare une étape de workflow répétée d’un corpus de beans quasi identiques.
La propriété est une passerelle de décision, pas une simple politesse. Un bean réservé par une autre session ne vous appartient pas pour être résolu, mis au rebut ou supprimé. La réservation est le moyen par lequel deux sessions évitent de prendre en charge le même élément ; clôturer celui d’autrui est le moyen pour l’une d’elles de perdre un travail dont elle n’avait pas encore fini de rendre compte.
« Bloqué » n’est pas synonyme de « non souhaité ». Un bean bloqué repasse à l’état todo avec son point de blocage consigné et une indication sur ce qui permettrait de le lever. Le laisser à l’état in-progress est pire que tout : un élément sur lequel personne n’avance apparaît, pour toutes les autres sessions, comme un travail actif.
Un bean n’est jamais supprimé
✎ Edit TR
beans delete existe dans la CLI. Ne l’utilisez pas.
Le travail qui s’avère ne pas être souhaité est mis au rebut — status: scrapped, avec une section expliquant pourquoi. C’est ce que signifie « désactiver » ici ; la CLI ne dispose d’aucun état désactivé, et son vocabulaire se résume à draft, todo, in-progress, completed, scrapped.
La raison n’est pas un souci d’ordre ou de propreté. Un bean mis au rebut consigne le fait qu’une chose a été envisagée puis rejetée, et pour quels motifs — ce qui a tout autant de valeur pour le prochain agent que l’enregistrement du travail accompli, car c’est ce qui évite de s’engager à nouveau dans la même impasse. Un bean supprimé empêche une session voisine de distinguer un abandon d’un accident, et laisse le prochain agent libre de recommencer à zéro sur ce que vous aviez déjà écarté.
Cette interdiction est formulée ici, ainsi que dans la documentation même du diagramme, précisément parce que l’outil propose cette opération. Une règle qui repose sur le fait que personne ne remarque une commande n’est pas une règle.
Les opérations du moteur ne sont pas des appels CLI
✎ Edit TR
Deux mécanismes différents peuvent modifier un bean, et une étape qui les confond annoncera un effet qu’elle ne produit pas.
Le moteur de workflow exécute claim, note et resolve sur le propre bean d’une instance de processus lorsqu’une étape marquée <cat-harness.processes:bean op="…"/> s’achève. claim définit l’état in-progress et est idempotent ; note ajoute des notes ; resolve marque le bean comme terminé uniquement une fois que l’instance elle-même est achevée, car déterminer si le travail est fait relève d’un jugement et qu’un bean ne se clôture pas sur la simple parole de quelqu’un d’autre.
L’agent accomplit tout le reste via la CLI beans : création, mise au rebut, renommage, définition d’un point de blocage. Le moteur ne dispose d’aucune opération pour aucune de ces actions.
Il ne s’agit pas d’une distinction théorique. Une activité dans le diagramme CRDM comportait <cat-harness.processes:bean action="create"/> — action, là où le moteur attend op — si bien qu’elle a été analysée comme une absence totale d’opération. L’étape annonçait que la validation produisait des beans, n’exécutait rien, et le faisait silencieusement jusqu’à ce que quelqu’un lise le parseur.
Lorsque vous ajoutez une étape marquée pour les beans, utilisez l’une des trois opérations implémentées par le moteur, et précisez dans la documentation de l’étape quelles parties relèvent des propres appels CLI de l’agent. bun run cat check:workflow-refs détectera une référence de compétence qui ne se résout pas ; il ne peut en revanche pas intercepter un attribut plausible que le moteur ne lit jamais.
Tâches humaines — pas encore construites
✎ Edit TR
Pas encore construites, et affirmé ici plutôt que laissé sous la forme d’une absence que quelqu’un devrait remarquer.
Les tâches d’une personne nécessitent leur propre cycle de vie, et rien de tout cela n’existe encore :
- Quand une tâche est affichée. Faire remonter chaque élément ouvert à chaque tour n’est que du bruit ; n’en faire remonter aucun aboutit à une liste que personne ne lit. Quelle que soit la règle retenue, elle ne sera pas identique à l’amorce du plan de travail qu’un agent reçoit au démarrage de sa session.
- Quand une personne peut en créer une, et par quel moyen — un salon de discussion, une commande, l’interface de démarrage de session.
- Comment une tâche est retirée. Qu’une personne abandonne un pense-bête est tout à fait ordinaire et n’exige aucune section « motifs de mise au rebut » ; les règles applicables aux beans ne sont pas transposables.
Tant que cela n’a pas été conçu, ne détournez pas les beans pour cet usage. Un espace de stockage dont les entrées sont réservées par des sessions, clôturées avec des résumés de modifications et jamais supprimées n’est pas adapté à un pense-bête que l’on souhaite abandonner sans formalité — et mélanger les deux introduirait dans le plan de travail de l’agent des éléments sur lesquels aucun agent ne devrait intervenir.
Ce que contient le plan de travail actuellement
✎ Edit QA TR
Le reste de cette page explique ce qu’est un bean. Cette section indique ce que le stockage contient actuellement — lu en direct depuis /assets/beans/index.json, la projection que gen-docs-pages.ts écrit à partir de beans/defs/ à chaque compilation, aux côtés de l’index des tâches qu’il publie depuis plus longtemps.
Jusqu’au 2026-09-20, il n’y avait rien à afficher ici. todos/ disposait d’un lecteur, d’un index publié et d’un tableau de bord par-dessus ; beans/ ne disposait d’aucun des trois, bien qu’il s’agisse d’un espace de stockage plus vaste de deux ordres de grandeur. Un plan de travail que personne ne peut consulter est un plan que personne ne vérifie.
Ce que montre le tableau de bord, et pourquoi chaque panneau a cette forme. Les totaux constituent l’information principale, ce sont donc des chiffres plutôt qu’un graphique à quatre barres répétant la même chose. La répartition par epic représente des ordres de grandeur entre des entités aux noms longs, elle prend donc la forme d’une barre horizontale. Les constats comportent trois ou quatre lignes, ils sont donc présentés sous forme de liste — avec une icône et un libellé à chaque ligne, car une couleur de statut n’est jamais porteuse de sens à elle seule.
Les constats sont calculés uniquement à partir de données commitées, et l’un d’eux est intentionnellement omis. Un détecteur d’éléments in-progress obsolètes devrait lire l’horloge système, or la projection est conditionnée à un contenu exact — tout élément calculé par rapport à l’horloge modifierait le fichier à chaque compilation, et la barrière d’obsolescence se déclencherait alors indéfiniment. La projection publie donc le updated_at de chaque bean comme un fait établi, et la page calcule l’ancienneté au moment où vous l’ouvrez. L’ancienneté évolue donc sans que le fichier ne change, ce qui est le fonctionnement logique.
Une vue plus complète existe, et elle est explorable. Chaque graphe d’états déclaré bénéficie de son propre visualiseur au chemin que cette instance utilise déjà pour ce graphe — /beans/, /todos/, et un pour chacun des autres. Cet itinéraire n’est pas une invention de cette page : le bean o7eq porte la décision du propriétaire selon laquelle un artefact rendu est adressé par le nom de son instance avec le graphe déclaré comme segment de chemin, et que cette instance omet son propre nom car son dossier docs/ est ce que le site sert, la compétence harness-requirements désignant cette URL exacte comme une obligation — « une exigence à leur égard est de fournir des visualiseurs accessibles à l’adresse <base-url>/beans ». Il n’y a pas d’index au-dessus d’eux, car / appartient au site de documentation ; chaque page liste donc ses homologues.
Un graphe sans projection l’indique explicitement. qa, health, issue-marks et uploads sont des graphes d’états déclarés pour lesquels rien ne publie encore de projection. Leurs tableaux de bord indiquent précisément cela et citent le bean 2krx, plutôt que d’afficher des zéros pour un stockage que personne n’a lu — un tableau de bord qui s’ouvre à zéro ne se distingue pas d’un stockage vide, or il s’agit de réalités opposées.
Chaque identifiant sur ces pages est un lien. Un identifiant de bean renvoie vers le fichier du bean, un numéro d’issue ou de pull request vers la forge logicielle, et chaque constat porte un crayon menant à l’endroit où l’écriture a effectivement lieu. Une référence qui ne peut pas être résolue reste sous forme de texte brut, ce qui marque visuellement la différence entre « suivez ceci » et « ceci pointe vers un endroit que je n’ai pas pu atteindre ».
Ce qui n’est pas présent ici. L’emplacement d’un bean dans un processus BPMN, qui constitue l’autre moitié du bean v49e. Cette jointure nécessite beans/workflows/, le graphe déclaré workflow-state, et celui-ci est vide — une vue de position indiquerait donc « nulle part » pour chaque bean du stockage. Elle attend que l’état d’instance existe.
Le tableau de bord interactif du plan de travail nécessite JavaScript. La projection qu'il lit est un simple fichier JSON et peut être lue directement.