Comments

Comments es el único registro de conversación de la raíz: comentarios en hilos sobre un Blueprint (el plano), un documento de nivel superior, una página de lienzo o una tarea, resueltos cuando se zanjan, firmados por quien los escribió. Cada hilo vive en el espacio de trabajo del plugin, y el plugin proyecta los hilos de un archivo en una región al pie de su cuerpo como markdown legible. El almacén es la verdad; la región es lo que muestra. Activo por defecto.

Un hilo apunta a su objetivo por un id permanente, nunca por una ruta, y a un lugar dentro de él por contenido (el texto de un encabezado, el texto de un elemento), nunca por número de línea. Una edición por encima no lo mueve; cuando el contenido al que apuntaba desaparece, el hilo se muestra huérfano en lugar de perseguirlo.

En el navegador

• En la página, los hilos están al pie del cuerpo en todos los modos, en el modal y en la página completa. Un + en un encabezado o en un criterio de aceptación empieza un hilo anclado ahí; @alias se completa con los usuarios de la raíz; un hilo tiene respuestas, Resolve y un borrar al pasar el ratón.
• Comments, una actividad en la barra de actividad con el recuento de hilos abiertos: cada hilo abierto por anfitrión con la etiqueta de su ancla y el último mensaje, que abre el objetivo en el ancla. Mostrar resueltos, mostrar huérfanos, Remove all orphaned, y en un hilo huérfano, volver a anclar, resolver o borrar. Un anfitrión desactivado deja sus hilos listados bajo Elsewhere.
• Un mensaje se firma con el usuario como quien actúa esta máquina (desde el shell, primero el usuario que nombran --as o EIDOS_USER); si no, con la identidad de git emparejada a un usuario listado a través del plugin Git; si no, con el nombre de git y el rol de me.md. Atribución, no autenticación.

Los hilos sobre una página de lienzo se dibujan como chinchetas; los hilos sobre una tarea están al pie de la tarea. Cada uno de esos anfitriones dice qué es un ancla. Canvas → · Backlog →

En disco

• .eidos/plugins/comments/threads/<thread-id>.yaml: un hilo. id; target { host, id } (host es blueprint, doc o el nombre de un plugin); at, las claves de ancla propias del anfitrión (las de un Blueprint son section, el texto de un encabezado, e item, el texto de un elemento), ausente en un hilo sobre el conjunto; resolved; messages[{ author, role?, user?, text, at }]. Un archivo editado a mano se lee tal como está escrito.
• .eidos/plugins/comments/settings.yaml: delete_orphaned, compartido, desactivado por defecto; activo, un hilo cuyo objetivo o ancla desapareció se borra en la siguiente lectura en lugar de listarse como huérfano.
• En cada archivo comentado, la región entre <!-- comments:threads --> y <!-- /comments:threads --> al pie del cuerpo: cada hilo, abierto y resuelto, como markdown. Se escribe con el primer hilo y se quita con el último, así que un archivo que nadie comentó no lleva región. Nunca escribas dentro; la siguiente reescritura la reemplaza entera. Un comentario es un guardado del archivo y aparece en el historial de git como tal.

Desde la terminal

eidos comments                                   # every open thread, grouped by host
eidos comments @login                            # the threads on one blueprint; --resolved, --json
eidos comments add @login "Is the limit per user?" --section "Behaviors"
eidos comments add @login "Per user." --reply <thread>
eidos comments add @login "Checked." --reply <thread> --as plato   # firmado como un usuario de la raíz
eidos users                                      # los usuarios de la raíz; --json
eidos users add "Plato" --alias plato --agent    # un usuario al vuelo: solo hace falta el nombre
eidos comments resolve @login <thread>           # --reopen
eidos comments delete @login <thread>
eidos comments project                           # rewrite every region that drifted; or one target

Un objetivo es una referencia a un Blueprint (@<id>, una ruta, un nombre de archivo), un documento o <host>:<id> (backlog:<task>, canvas:<page>). --section, --item y --at key=value anclan un hilo dentro de su objetivo.

Un agente lee los hilos de un objetivo antes de editarlo, responde a una pregunta con add --reply y resuelve solo cuando el dueño dice que algo está zanjado. El comando firma el mensaje; un archivo de hilo nunca se edita para comentar.

Un agente comenta como sí mismo, nunca como la persona para la que trabaja. Sin --as, un comentario se firma con el usuario que actúa, que en la copia de alguien es esa persona. Así que un agente mira eidos users, se añade una vez con eidos users add "<Su nombre>" --alias <alias> --agent cuando no está (no hace falta rol), y pasa --as <alias> en cada comments add. Un nombre que no es de ningún usuario se rechaza con el eidos users add que lo crea. Plato arranca su agente firmando como el usuario como quien actúa, por defecto un usuario Plato que añade a los usuarios de la raíz; con Plato como usuario apagado en los ajustes de Plato, su agente no comenta como nadie y cada comentario que intenta se rechaza. En la página de ajustes Users, el interruptor Agente de una fila marca a un usuario como agente.

Qué informa la comprobación

comments/anchor-missing (un hilo cuyo anfitrión dice que su objetivo o ancla ya no resuelve) y comments/region-stale (un archivo cuya región no es lo que el almacén escribiría, incluida una que quedó atrás tras borrar su último hilo). Project arregla la segunda.