docs: rethink the 12 factors from first principles

[boshu2]

What this is

A first-principles rethink of the twelve factors, as a design proposal (docs/plans/2026-05-29-first-principles-rethink.md). No factor files change — this is the design-then-implement step the repo already uses (cf. the 2026-02-15 pivot design).

Method

Rather than edit the existing list (which yields reshuffles, not rethinks), it starts from six irreducible facts about what an LLM agent is, derives the disciplines those facts force, and only then lays the result next to today's twelve.

The six axioms: the actor is stateless/frozen; attention is finite/non-uniform; the actor can't certify itself; output is non-deterministic and cheap to regenerate; experience evaporates unless externalized; actions have irreversible consequences. (These are the same six primitives in operator-model.md — derived rather than asserted, which is itself a result: the compression layer survives a from-scratch derivation.)

Findings

The derivation validates most of v3, and surfaces two things:

• One redundancy — the knowledge loop is split across Factors VII / VIII / XII when it is one machine (extract → store → re-inject; failures and wins feed the same loop). The operator-model crosswalk already routes VII and XII to the same primitive; the factor surface hasn't caught up.
• One genuine gap — nothing covers the agent–world boundary: authority, blast radius, reversibility. "Isolate Workers" is agent-vs-agent; "Supervise Hierarchically" is the escalation tree; neither is least-privilege / reversible-by-default / contained blast radius. This is the change most justified by what changed in the world — agents now act directly (shell, deploy, spend, prod), where v1 (2025) mostly proposed code a human ran.

Proposed change (brand-preserving — count stays at 12)

1. Fuse VII + VIII + XII into one promotion-loop factor, keeping the three failure modes (don't extract / never re-inject / ignore failures) as named sub-points.
2. Add "Bound authority & blast radius."
3. Reframe IV and V as the before/after halves of binding the actor to reality, with reality (compiles? test passes? prod up?) as the primary validator, not just a second agent.
4. Keep the public tier names; add a six-axiom grouping to operator-model.md as the conceptual spine.

The doc includes a pre-mortem against itself (churn risk, lost accountability from the fusion, overlap objections) and an explicit note that twelve is inherited, not derived — held open so the maintainer chooses with eyes open.

Next step if accepted

Phased rewrite of factors/ mirroring the pivot sequence: archive, write the fused loop + new authority factor, reframe IV/V, update README crosswalk + operator-model.md, extend GOALS.yaml. Happy to take that on as a follow-up.

https://claude.ai/code/session_01EwKYoMnRBRi2KkAQYzUn4D

---

Generated by Claude Code