From c6a92735d3836156ef5f803cbecea24574f337a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Mon, 24 Aug 2026 16:38:33 +0000 Subject: [PATCH] a commander is told its shape at creation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit trigger, action, ledger — settled with the owner over several turns and true of every commander, so it belongs in the file each one reads at session start rather than being re-derived in conversation each time. the part that took the longest to see: an action that takes ONE item all the way through means a half-finished item never exists, so there is nothing to queue and no second watcher needed to notice it. this commander was built as two cycles — transcribe everything, then file everything — and the second cycle existed only to clean up after the first stopped early. and the ledger keys on a hash of the SOURCE. names change (a memo renamed from a phone), outputs move (a transcript filed into a category folder), and both of those had already caused the same file to be handled twice. Co-Authored-By: Claude Opus 5 Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043 --- src/servers/api/command-hq/directory.ts | 43 +++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/src/servers/api/command-hq/directory.ts b/src/servers/api/command-hq/directory.ts index 6091dcbb..60aef6a5 100644 --- a/src/servers/api/command-hq/directory.ts +++ b/src/servers/api/command-hq/directory.ts @@ -163,6 +163,49 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string { 'record is the only one. Without it, deleting this commander leaves its loop running.', '', ...credentialSection(params.credentialPath), + '## The shape: one trigger, one action, one ledger', + '', + 'Settled with the owner and true of every commander, not just this one. Read it before designing a', + 'watcher; most of it was learned by getting it wrong.', + '', + '**One trigger.** A schedule that asks a single question: what has appeared that I have not handled?', + 'The trigger runs constantly, so it must never need judgement. If deciding whether something happened', + 'takes thought, the condition is too vague — it will either never fire or fire constantly, and you will', + 'find out days later.', + '', + '**One action, and it takes ONE item all the way through.** Not a stage at a time across everything.', + 'Transcribe this file, classify it, dispatch it, done — then the next file. The reason is not tidiness:', + 'a half-finished item is a STATE, and a state needs a second watcher to notice it and a second record to', + 'track it. Going end to end per item means that state never exists, so there is nothing to queue.', + '', + 'The cost is real and worth knowing. If the last step fails, the earlier ones are not recorded and get', + 'redone. That is fine for cheap work and not fine for forty minutes of audio — so when a step is', + 'expensive, record which step was reached and resume there.', + '', + '**One ledger, appended after the work.** One line per item, written when it is finished, never before.', + 'A crash between doing the work and writing the line costs a repeat; the other order loses the item', + 'silently. Append, never rewrite — two writers cannot corrupt an append.', + '', + 'Key it on a HASH of the source, not a name. Names change: a recording gets renamed from a phone, a', + 'file is moved, and a name-keyed ledger quietly does all of it again. Do not key it on the OUTPUT', + 'either — outputs move, get filed, get renamed. The source is the only thing that holds still.', + '', + 'Two consequences to accept deliberately. The same content under two names is one item, done once. And', + 'deleting an output does not bring it back, because the ledger still says done.', + '', + '**Never write into what you watch.** The reference path holds its subject and nothing of yours. Your', + 'outputs, records and logs live here, in your own directory.', + '', + '**A spawned agent follows a FILE, not a prompt.** Put the rules in `procedures/.md` here and', + 'point the agent at it. When the rule changes you edit one document; a prompt baked into a loop is a', + 'rule nobody can find and nobody reviews.', + '', + '**Say what is provisional.** A two-minute cadence chosen for testing reads a week later as a decision', + 'somebody made. Write down which numbers were guesses, so the next turn knows what it may change.', + '', + '**Leave the ambiguous alone and name it.** An item you cannot confidently handle stays unhandled and', + 'goes in the report. Forcing a guess makes it look like a decision, and nobody looks at it again.', + '', '## Before arming anything', '', 'Never arm a watcher on the first turn. The first turn is for settling what to watch and what to do',