Clanker Discipline

# Clanker Discipline

Apply these rules when writing or reviewing state types, data models, and functions that manage application state. Agents tend to add flags, optional fields, and special cases that compound into state nobody intended — catch that before it lands.

When you find violations, refactor fully. The goal is clean, maintainable code, not minimal diffs. Rip out the flags, reshape the types, restructure the functions. A bigger diff now is better than layering workarounds that compound later.

---

## 1. Derive, don't store

Every boolean you add doubles the theoretical state space. When a value can be derived from data you already have, do not store it. The best source to derive from is an event stream: a log of what happened.

### Before: cached flags

An agent was asked to show a footer only when the assistant finishes naturally. It invented four flags:

```ts
type ThreadState = {
  wasInterrupted: boolean;
  didAssistantFinish: boolean;
  didAssistantError: boolean;
  wasToolCallOnly: boolean;
};

function shouldShowFooter(state: ThreadState): boolean {
  return state.didAssistantFinish
    && !state.wasInterrupted
    && !state.didAssistantError
    && !state.wasToolCallOnly;
}
```

Four fields to answer one question, with four mutation sites elsewhere keeping them in sync.

### After: derive from evidence

```ts
function shouldShowFooter(events: SessionEvent[]): boolean {
  const latest = getLatestAssistantMessage(events);
  if (!latest) return false;
  return latest.completed && !latest.error && latest.finish !== 'tool-calls';
}
```

The answer is now computed from events that already exist.

### When NOT to derive

- The domain genuinely has a state machine with ordered transitions. A checkout step is not a cached conclusion; it IS the state.
- A field contains temporal or external data that cannot be rederived (timestamps from async processes, API responses needed downstream).
- The derivation would be more complex than the stored value.

### If you cannot derive, encapsulate

If mutable state must exist, trap it in the smallest possible scope. A closure is better than a class field:

```ts
// Bad: state visible to the whole class
class Writer {
  private debounceTimeout: ReturnType<typeof setTimeout> | null = null;
  queueSend(text: string) { /* can touch debounceTimeout */ }
  flushNow() { /* can touch debounceTimeout */ }
  somethingElse() { /* can also touch debounceTimeout */ }
}

// Good: state trapped in a closure
function createDebouncedAction(callback: () => void, delayMs = 300) {
  let timeout: ReturnType<typeof setTimeout> | null = null;
  return {
    trigger() {
      clearTimeout(timeout!);
      timeout = setTimeout(() => { timeout = null; callback(); }, delayMs);
    },
    clear() {
      if (timeout) { clearTimeout(timeout); timeout = null; }
    },
  };
}
```

Nothing outside the closure can touch the timer.

### The debugging payoff

When state is derived from evidence, debugging becomes data-in, answer-out:

```ts
test('footer is hidden for aborted runs', () => {
  const events = loadEvents('./fixtures/aborted-session.jsonl');
  expect(shouldShowFooter(events)).toBe(false);
});
```

No mocking or timing reproduction. The bug is in the events or in the pure function.

---

## 2. Make wrong states impossible

Every optional field is a question the rest of the codebase must answer every time it touches that data.

### Discriminated unions over optional bags

```ts
// Bad: when status is 'idle', should gateway/transactionId exist? The type doesn't say.
type PaymentState = {
  status: 'idle' | 'processing' | 'settled';
  gateway?: 'stripe' | 'paypal';
  transactionId?: string;
  initiatedAt?: string;
  settledAt?: string;
};

// Good: each status carries exactly the fi