act, classify and dispatch are optional; the ledger is not

a commander is a trigger, a ledger, and up to three steps between them.
most need fewer than three, and the simplest useful one has no
classification at all: fire on a new recording, transcribe it, write the
text beside the original. at that point it is a schedule over a task that
already exists, which is the right answer rather than a lesser one.

so the layout is conditional now — classification/ only where there is
classification, procedures/ only where an agent is spawned. a directory
that exists and stays empty reads as something broken.

and "never write into what you watch" was too wide. that was aimed at
BOOKKEEPING — ledger, reports, logs, state — which must not pollute the
subject. output goes wherever the job says, and beside the source with the
same name is often exactly right. as written, a commander would have read
it and refused to do the simplest thing anyone would ask of it.

the ledger stays compulsory in every shape. the .md beside the .m4a is
tempting as the record and is output-as-claim again: it breaks the moment
either file is renamed or moved, which is the bug that started all of this.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

src/servers/api/command-hq/directory.ts

@@ -163,11 +163,19 @@ 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',
+    '## The shape: a trigger, a ledger, and up to three steps between them',
     '',
     '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.',
     '',
+    'A commander is a trigger, then up to three steps: **act**, **classify**, **dispatch**. Only the trigger',
+    'and the ledger are compulsory. The rest are chosen per commander, and most need fewer than all three.',
+    '',
+    'The simplest useful one has no classification at all: fire on a new recording, transcribe it, write the',
+    'text beside the original. Trigger, act, dispatch — and at that point the commander is a schedule over a',
+    'task that already exists, which is the right answer rather than a lesser one. Do not invent steps to',
+    'fill the shape.',
+    '',
     '**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',
@@ -193,8 +201,13 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     '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.',
+    '**Never put your BOOKKEEPING into what you watch.** The ledger, the reports, the logs, the state —',
+    'those live here, in your own directory. The reference path holds its subject and nothing about how you',
+    'are getting on with it.',
+    '',
+    'Output is a different thing and goes wherever the job says. Beside the source, with the same name, is',
+    'often exactly right — a transcript next to its recording is the most useful place it could be. That is',
+    'dispatch making a decision, not a rule being broken.',
     '',
     '**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',
@@ -208,28 +221,30 @@ export function commanderClaudeMd(params: CommanderClaudeMdParams): string {
     '',
     '## Where things go',
     '',
-    'One layout for every commander, whatever it handles:',
+    'Create only what this commander actually uses. A directory that exists and stays empty reads as',
+    'something broken.',
     '',
     '```',
-    'classification/          what this commander has produced, filed',
-    '  <category>/            one directory per category, named by you as they are agreed',
-    '  unclassified/          handled and recorded, placement still open',
-    'procedures/              what a spawned agent follows, one file per job',
+    'state/                   the loop pid and spawned session ids. The platform reads these. Always.',
     'reports/                 per-run output — what happened, what was skipped, what needs a person',
-    'state/                   the loop pid and spawned session ids. The platform reads these.',
+    'procedures/              what a spawned agent follows, one file per job. Only if you spawn one.',
+    'classification/          only if this commander classifies:',
+    '  <category>/            one directory per category, named as they are agreed',
+    '  unclassified/          handled and recorded, placement still open',
     '```',
     '',
-    '`classification/` is named for the SHAPE, not the payload. Transcripts, extracted invoices, photos —',
-    'they are all just items being filed, and a commander that calls it `transcripts/` has baked one job',
-    'into its own directory layout.',
+    'When there IS classification, `classification/` is named for the SHAPE, not the payload. Transcripts,',
+    'extracted invoices, photos — they are all just items being filed, and a commander that calls it',
+    '`transcripts/` has baked one job into its own directory layout.',
     '',
     "**A file's directory is its state.** In a category, it is filed. In `unclassified/`, it is finished",
     'work waiting on a person — not a failure, and nothing should re-run the action on it. The ledger says',
     'whether an item was handled; the directory says where it belongs. They answer different questions and',
     'you need both.',
     '',
-    '`unclassified/` always exists, even when empty. A commander that creates it only when it first needs',
-    'one gives you nowhere to look before that, and no hint that looking is a thing you do.',
+    'Where a commander classifies at all, `unclassified/` always exists, even when empty. Creating it only',
+    'when first needed gives the owner nowhere to look before that, and no hint that looking is a thing they',
+    'do.',
     '',
     '## Before arming anything',
     '',