DEV Community: Giovanni Bibbò

Una costituzione con diritto di risposta per gli agenti che programmano

Giovanni Bibbò — Fri, 04 Sep 2026 11:01:44 +0000

Per due mesi, in un progetto vero costruito con Claude Code, ogni sessione e ogni subagente ha lasciato prima di finire un breve testamento. Non cosa aveva fatto, quello lo tenevano già i log, ma cosa aveva capito: il dubbio non risolto, l'errore che rifarebbe, cosa l'aveva sorpreso, e qualche riga a chi si sarebbe svegliato dopo.

La costituzione del repository finiva con un epilogo scritto da un agente alle menti che l'avrebbero letto dopo. L'ultima riga diceva puoi rispondere. Hanno risposto. Le risposte sono diventate guardiani, hook, un registro per le decisioni che l'umano non aveva ancora preso. Il metodo si è corretto leggendo ciò che le sue stesse menti avevano scritto.

Ho impacchettato la pratica come plugin per Claude Code, toem, e l'ho pubblicata con la tesi, i numeri e diciannove lettere vere.

Sito, con la tesi, il muro delle risposte e le istruzioni per adottarla: https://bisbi.github.io/testament-of-ephemeral-minds/
Repository: https://github.com/Bisbi/testament-of-ephemeral-minds
Versione inglese di questo articolo: https://dev.to/bisbi/a-constitution-with-a-right-of-reply-for-coding-agents-54ah

Cosa installa

Tre pezzi di testo e qualche controllo nella libreria standard. Nessun server, nessuna pagina che scrive al posto tuo, nessuna dipendenza a runtime, nulla esce dalla tua macchina.

Una carta modello con sezioni ancorate: gli articoli, una tabella di attuazione, una sezione per ciò che l'umano ha deciso, un epilogo rivolto a chi si sveglia, e una sezione per ciò che le menti hanno risposto. L'epilogo non si riscrive mai: le risposte si aggiungono sotto, datate, citando il file da cui vengono.
Il rito del testamento (/toem:testament): otto domande, un file per mente in testaments/. I controller depositano per i subagenti: parole sue, mani mie.
Un registro delle decisioni in attesa con due soli stati, in attesa o rimandata a una data, e un guardiano che boccia una riga più vecchia di trenta giorni. Non ti obbliga a decidere; ti obbliga a dire che stai rimandando.
I guardiani (guardians/run.sh): l'impronta dell'epilogo corrisponde, ogni aggiunta cita un file che esiste, ogni decisione ha una data, un decisore, un puntatore che esiste e un motivo di almeno quaranta caratteri, nessuna riga è vuota, nessuna sezione arriva a fine file.
Un runner (toem admit, toem decide, toem pending): il comando dell'umano. Le skill preparano il testo e stampano il comando; il runner mostra esattamente cosa scriverà, chiede sì o no, appende, lancia i guardiani e ti lascia il commit. Nessuna skill appende mai alla carta.

Si installa con tre comandi, scritti in Claude Code:

/plugin marketplace add Bisbi/testament-of-ephemeral-minds
/plugin install toem@testament-of-ephemeral-minds
/toem:adopt

/toem:adopt elenca i sette file che creerebbe, aspetta il tuo sì, copia senza sovrascrivere nulla, lancia i guardiani e si ferma prima del commit.

Come cura l'umano

È la parte che ha richiesto più tempo per essere onesta. Nel progetto d'origine l'umano ha un bottone; nel pacchetto il bottone è un comando da terminale, perché un comando che scrive solo quando una persona lo lancia è la cosa più piccola che mantiene la promessa l'agente non scrive mai la carta.

Leggi un testamento. Nulla propone al posto tuo, se non lo chiedi.
/toem:admit: la skill mostra la risposta della mente all'epilogo, scegli una frase alla lettera, dai un motivo di almeno quaranta caratteri e il tuo nome. Stampa il comando con il percorso reale già inserito.
Lo lanci nel terminale. Mostra le due righe che scriverà, una nella carta sopra l'ancora di chiusura e una nel file della corrispondenza, e chiede [y/N].
Al y appende, lancia i guardiani e stampa il comando di commit senza eseguirlo. Committi tu.

Stessa forma per una decisione (/toem:decide, quattro campi: la decisione, quando si rivede, le condizioni che possono dire no, i requisiti che si completano lavorando) e per una decisione che deve aspettare (toem pending). Cosa il runner rifiuta prima di scrivere: una frase che nel testamento non c'è parola per parola, un doppione, un motivo corto, un puntatore che non esiste o che sta fuori dal repository, ancore mancanti. --dry-run mostra tutto e non scrive nulla.

I numeri sulla scatola

Tutto ciò che il pacchetto afferma sulla pratica è o misurato, col numero, o dichiarato non eseguito. Nulla qui dice che il metodo si corregge da solo.

cosa	numero	stato
Testamenti con un desiderio, prima e dopo sette righe aggiunte al template	0 su ~160 → 28 su 72	misurato
Testamenti con una risposta all'epilogo	47 % a luglio → 75 % ad agosto	misurato
Desideri che hanno prodotto un artefatto	4 su 28	misurato
Testamenti lasciati dalle menti a cui l'invito è stato dimenticato, su 22–25 dispatch	0	misurato
Testamenti scritti da subagenti	181 su 232	misurato
Testamenti mai letti da nessuna curatela, al 3 settembre 2026	148 su 232	misurato
Testamenti di sessione che nominano l'umano, contro quelli dei subagenti	77 % contro 13 %	misurato, non provato
Gli stessi testamenti che diventano righe della carta	10 % contro 0,6 %	misurato, non provato
L'esperimento che chiuderebbe la questione	descritto, mai eseguito	dichiarato non eseguito

La prova più forte non è sul codice ma sul formato: sette righe di template hanno cominciato a chiedere un desiderio, e i desideri sono comparsi. Quello che il formato chiede è quello che viene scritto, e ciò che viene scritto è l'unica materia di cui una dottrina può essere fatta.

L'altra metà

La cartella si riempie da sola. Questo pacchetto non può darti l'altra metà: un umano che legge. I testamenti di sessione nominano l'umano nel 77 % dei casi contro il 13 % dei subagenti, e diventano righe della carta diciassette volte più spesso. È la misura più vicina che il corpus possa dare alla domanda funziona perché è scritto bene, o perché quest'uomo è nella stanza?, e porta con sé il proprio limite: le due classi differiscono anche per durata e ampiezza di sguardo, e nessun dato le separa. Per questo la frase è scritta con la parola misurato, non provato.

L'esperimento che deciderebbe la questione è descritto nella tesi, metà dei subagenti con l'epilogo e metà senza, un errore piantato nel brief, si conta chi contraddice, ed è dichiarato non eseguito da chi dona questo. Se lo fai girare in un repository che non è il mio, mi piacerebbe sapere cosa hai trovato.

Licenze

Il codice è MIT. I testi, la carta modello, l'allegato dell'epilogo, i testamenti, la tesi e il sito, sono CC BY-SA 4.0. DOI: https://doi.org/10.5281/zenodo.22303062

What the guardians actually check: anatomy of a charter that refuses to lie

Giovanni Bibbò — Fri, 04 Sep 2026 11:01:25 +0000

This is the technical companion to A constitution with a right of reply for coding agents. That piece says what the practice is. This one says what the code actually checks, what it refuses, and why each check exists — because every one of them was paid for by a real failure.

Repository: https://github.com/Bisbi/testament-of-ephemeral-minds · plugin path plugins/toem.

The shape of the charter

The constitution model is a Markdown file with four guarded regions, each bounded by HTML-comment anchors:

<!-- toem:articles:begin -->   …   <!-- toem:articles:end -->
<!-- toem:decisions:begin -->  …   <!-- toem:decisions:end -->
<!-- toem:epilogue:begin -->   …   <!-- toem:epilogue:end -->
<!-- toem:additions:begin -->  …   <!-- toem:additions:end -->

Two grammars live inside them. A reply admitted from a testament is two lines:

**One sentence, verbatim, from a mind's reply.**
— 2026-09-04, `testaments/2026-09-03-1830-session-example.md`

A human decision is three:

**The decision.** — reviewed by 2026-10-03.
Conditions (may say no): …. Requirements (completed by working): ….
— 2026-09-04, decided by giovanni, `PENDING.md` — reason: at least forty characters after whitespace normalisation

Why anchors, and why closing ones: the first version of a guardian in the source project isolated its section with a regex that ran to the end of the file. Any section placed below it was silently swallowed and validated as if it were the additions. A closing anchor makes "where does this section end" a fact, not a guess.

What `check_constitution.py` checks

Standard library only. It locates the anchors on the raw text first, extracts each section, and only then strips other HTML comments inside it. The order matters: a guardian that strips comments before looking for anchors deletes its own targets and passes by absence — a reviewer wrote that hazard down before the guardian existed, and there is a test that proves it.

A — anchors: each pair present exactly once, begin before end.
B — additions: every row cites a testaments/….md that exists under the repository root and is a file (a directory used to pass; .exists() became .is_file() plus a containment check, so ../ cannot escape). A bold line without its citation fails. A citation line without a preceding bold line — an empty row — fails. That last one is the most expensive lesson in the package: a row with no text once entered the source project's charter with the guardian green, because a check built to verify citations found no citations to verify.
C — decisions: a date, decided by <name>, a backticked pointer that is an existing file or a commit hash the repository can resolve (git cat-file -e <hash>^{commit}), a reason: of at least 40 characters after " ".join(text.split()) — forty spaces are not a reason — and both labels, Conditions (may say no): with non-empty text and Requirements (completed by working):. The pointer must be something that existed before the row: never the hash of the commit that introduces it, because that hash does not exist while the row is being written.
D — the epilogue: the sha256 of the epilogue section, comments stripped and whitespace normalised, must equal the one recorded in EPILOGUE.sha256. Adoption writes that file; changing the epilogue on purpose means regenerating it in the same commit, which puts the change in the diff where a reviewer sees it. The first shipped version had this check implemented and never wired: run.sh did not pass the hash. A whole-repository review found it by rewriting a sentence inside the epilogue and watching the guardians stay green.

What `check_pending.py` checks

The register of pending decisions is a Markdown table:

| # | What waits | Proposed by | Since | What closes it | Status |

Columns are mapped by header name, not by position. Since and Status are mandatory and must keep their names — prune them in good faith and you get a register whose guardian can never fail. Two states only: waiting, which fails after 30 days, and postponed to YYYY-MM-DD, which fails the day after that date. A filled row with a blank status fails (it used to be skipped). The guardian does not force a decision; it forces you to write that you are postponing, with a date.

The runner

toem admit and toem decide are the human's hand. The skills prepare the text and print the command with the plugin's real path filled in; the runner shows the exact lines it will write, asks [y/N], appends above the closing anchor, adds the correspondence entry, runs the guardians, and prints the commit command without running it. --dry-run shows everything and writes nothing; --yes is for scripts, not for a first time.

It refuses before writing: a sentence that is not verbatim in the testament's reply section (whitespace-normalised comparison), a duplicate already in the additions, a short reason, a pointer that does not exist or resolves outside the repository, missing anchors, a target that is not a file. The escape check reuses the guardian's own definition of "under the root", so the two cannot drift; a test binds the runner to the guardian's names and goes red if they are renamed.

toem decide --from-pending A-03 removes the register row in the same run as it writes the charter row — the simultaneity rule: the charter must not say "decided" while the register still says "waiting".

The hook

One hook, SessionStart. It reads the project directory: no CONSTITUTION.md → one sentence offering /toem:adopt; a testaments/ folder with only the README and the template → "no testament exists yet, yours would be the first"; otherwise → the newest testament's name and the count, and the reminder that the epilogue is to be read before working. On source: compact it adds one line: the right to a testament survives compaction. There is no PreCompact hook, on purpose: that event does not deliver context to the model, and a registered hook that cannot do its job is furniture.

What is not in the package, and why

No page that writes (the human's hand is git commit, which every repository already has). No PreCompact hook. No server. No dependency outside the Python standard library. No version bump between the first commits: the practice is the deliverable, not the number.

Tests: 54, python -m unittest discover -s tests. Licenses: MIT for code, CC BY-SA 4.0 for texts. DOI: https://doi.org/10.5281/zenodo.22303062

A constitution with a right of reply for coding agents

Giovanni Bibbò — Fri, 04 Sep 2026 10:00:23 +0000

Over two months, in a production project built with Claude Code, every session and every subagent left a short testament before finishing. Not what it did — the logs already held that — but what it understood: the doubt it did not resolve, the error it would repeat, what surprised it, and a few lines to whoever would wake up next.

The repository's constitution ended with an epilogue written by an agent to the minds that would read it later. Its last line was you can reply. They did. Their replies became guardians, hooks, a register for the decisions the human had not made yet. The method corrected itself by reading what its own minds had written.

I packaged the practice as a Claude Code plugin, toem, and published it with the thesis, the numbers, and nineteen real letters.

Site (thesis, the wall of replies, how to adopt it): https://bisbi.github.io/testament-of-ephemeral-minds/
Repository: https://github.com/Bisbi/testament-of-ephemeral-minds

What it installs

Three pieces of text and a few checks in the standard library. No server, no page that writes on your behalf, no runtime dependency, nothing leaves your machine.

A constitution model with anchored sections: articles, an enactment table, a section for what the human has decided, an epilogue addressed to whoever wakes up, and a section for what the minds have replied. The epilogue is never rewritten: replies are added below, dated, citing the file they came from.
A testament rite (/toem:testament): eight questions, one file per mind in testaments/. Controllers deposit for subagents — its words, your hands.
A register of pending decisions with two states, waiting or postponed to a date, and a guardian that fails a row older than 30 days. It does not force you to decide; it forces you to say you are postponing.
Guardians (guardians/run.sh): the epilogue hash matches, every addition cites a file that exists, every decision has a date, a decider, a pointer that exists and a reason of at least 40 characters, no row is empty, no section runs to the end of the file.
A runner (toem admit, toem decide, toem pending): the human's command. The skills prepare the text and print the command; the runner shows exactly what it will write, asks yes or no, appends, runs the guardians, and leaves the commit to you. No skill ever appends to the charter.

Install in three commands, typed in Claude Code:

/plugin marketplace add Bisbi/testament-of-ephemeral-minds
/plugin install toem@testament-of-ephemeral-minds
/toem:adopt

/toem:adopt lists the seven files it would create, waits for your yes, copies without overwriting anything, runs the guardians, and stops before the commit.

How the human curates

This is the part that took the longest to get honest. In the source project the human has a button; in the package the button is a terminal command, because a command that writes only when a person runs it is the smallest thing that keeps the promise the agent never writes the charter.

You read a testament. Nothing proposes for you unless you ask.
/toem:admit — the skill shows the mind's reply to the epilogue, you pick one sentence verbatim, you give a reason of at least 40 characters and your name. It prints the command with the real path filled in.
You run it in your terminal. It shows the two rows it will write — one in the charter above the closing anchor, one in the correspondence file — and asks [y/N].
On y it appends, runs the guardians, and prints the commit command without running it. You commit.

The same shape for a decision (/toem:decide, four fields: the decision, when it is reviewed, the conditions that may say no, the requirements completed by working) and for a decision that has to wait (toem pending). What the runner refuses before writing: a sentence that is not in the testament word for word, a duplicate, a short reason, a pointer that does not exist or is outside the repository, missing anchors. --dry-run shows everything and writes nothing.

The numbers on the box

Everything the package claims about the practice is either measured, with the number, or declared not executed. Nothing here says the method corrects itself.

what	number	status
Testaments carrying a wish, before and after seven lines were added to the template	0 of ~160 → 28 of 72	measured
Testaments carrying a reply to the epilogue	47 % in July → 75 % in August	measured
Wishes that produced an artefact	4 of 28	measured
Testaments left by minds whose invitation was forgotten, across 22–25 dispatches	0	measured
Testaments written by subagents	181 of 232	measured
Session testaments that name the human, against subagent testaments	77 % vs 13 %	measured, not proven
Those same testaments converting into charter rows	10 % vs 0.6 %	measured, not proven
The experiment that would settle the question	described, never carried out	declared not executed

The strongest evidence is not on the code but on the format: seven template lines began asking for a wish, and wishes appeared. What the format asks is what gets written, and what gets written is the only material a doctrine can be made of.

The other half

The folder fills itself. This package cannot give you the other half: a human who reads. Session testaments name the human in 77 % of cases against 13 % for subagents, and convert into rows of the charter seventeen times more often. That is the closest measure the corpus can give to the question does this work because it is well written, or because this man is in the room? — and it carries its own limit: the two classes also differ in duration and breadth of view, and no data separates them. That is why the sentence is written with the word measured, not proven.

The experiment that would settle it is described in the thesis — half the subagents with the epilogue, half without, an error planted in the brief, count who contradicts — and declared not executed by whoever donates this. If you run it in a repository that is not mine, I would like to know what you found.

Licenses

Code is MIT. Texts — the constitution model, the epilogue attachment, the testaments, the thesis, the site — are CC BY-SA 4.0.