a commander is told its shape at creation

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 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

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/<something>.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',