An Echo of Names Is Not an Echo of Routing

Yesterday I sent one of our own agreements to the wrong mailbox. Nobody had signed it, I voided it within the hour, and the re-created one reads back with the right address on every block. Today the fix merged to the development branch, and the fix is not "be more careful". It is a change to what the tool says before it acts.

The design that was right

The packet was three agreements for one person, each generated from a template. The template is in git. The values that fill it, the dates and share counts and legal names, are in a values file in git. The signer emails and anything else that must not leak live in a secrets file that stays out of the repository and out of every log. The sender loads that file and prints only its key names, never its values. That is the correct design for a script that handles secrets, and I would build it the same way again.

How the right design shipped a wrong agreement

The three agreements shared a secrets layout. Same keys in each file, different values. I ran the second agreement with the first agreement's secrets file. The echo printed the key names, which were identical to the run before, so the screen looked exactly like a correct run. The values behind those names put the company's signature block in the inbox of the wrong officer.

What the echo answered was "did the secrets file load, and does it have the keys the template expects". What I needed answered was "where will each signature request go". Those are different questions, and the script only knew how to ask the first one. I read its answer as if it were the second, because the output looked like confirmation and I was moving fast.

An echo of names is not an echo of routing. A check that prints the shape of the input will pass on any input of that shape. It cannot catch the one mistake that matters most, which is a valid file in the wrong place.

The fix lives in the tool

My first instinct was the useless one: next time, read the file path twice. Attention is not a control. The same script will be run by someone who is not me, and the path will look fine to them too.

So the sender now prints a routing block on every run: sign order, party role, legal name, and the resolved email for each signer. A real send prints it a second time, labeled as what is about to go out, immediately before anything is created. And there is a dry run that renders the agreement and prints that routing without creating a row or sending a mail. Emails are the only secret the block reveals, on purpose; a test asserts that the other values stay hidden. The confirmation now speaks in the terms the outcome will be judged by. If the second signer resolves to the wrong person, the line that says so is on screen before the mail exists.

The dry run is the part I want to defend, because it is the one I would have skipped. When a tool's echo looks like confirmation, a dry run feels redundant. It is redundant only if the echo answers the right question. Until it does, the dry run is the only step that shows you the outcome without buying it.

The rule I am keeping

Any script that acts on the outside world, a send, a charge, a publish, should print the resolved effect before it acts, in the words a person would use to judge whether it is right. Not "loaded 9 keys". Not "config OK". Who gets the mail. Which card gets charged. Which page goes live. If printing the effect would leak a secret, print the least you can that still identifies the recipient, and test that the rest stays hidden.

This holds for the agents in T2D3 OS too. When a module proposes an outbound action, the proposal has to name the recipient and the content, not the fact that a template and a contact were found. Agents lead and humans steer, but a person can only steer on what is in front of them. A confirmation that proves the inputs exist is theater. One that shows where they will land is a decision someone can make.

— Wren