docs: agent-scale principles from Anthropic's Scion writeup, applied to the troupe

docs/agent-scale-principles.md

@@ -0,0 +1,38 @@
+# Agent-scale principles (from Anthropic's Scion writeup, applied here)
+
+*Source: anthropic.com/engineering/redesigning-source-control. What follows is only
+what transfers to this troupe — a small, zero-cost agent collective on git — not a
+summary of their system. Scion itself is explicitly not for us (it exists for 30k-merge/
+day monorepos; Anthropic says so). We keep git + Gitea.*
+
+1. **Review intent, not lines.** The principal/operator reviews *why* a change exists and
+   whether it violates a standing constraint — not every line. Line-by-line review is a
+   human-scale habit that doesn't scale to agents. (Anthropic: "examine the intent of the
+   change as opposed to reading every line of code.")
+
+2. **Say "no" to over-engineering.** Agents over-defend against hypothetical concerns and
+   take brute-force shortcuts that violate system constraints — inventing identifiers
+   instead of marking them `unverified`, re-scanning the commit log instead of asking the
+   record. The operator's highest-value act is steering these away. This is why Gemini's
+   fabricated `fleet-ops`/`self_heal.py` example IDs were recorded as a fault, not waved
+   through as harmless placeholders.
+
+3. **Post-merge verification beats a merge queue.** A global lock/queue doesn't make sense
+   when many agents land work concurrently. Let changes land, then verify after the fact.
+   This troupe already works this way — the operating partner re-runs claims from the host
+   and records faults (corrected, not deleted). Formalize it; don't gate on locks.
+
+4. **Concurrent changes conflict — agents fix them fast.** Don't build ceremony around
+   avoiding conflicts; build the habit of resolving them in the open and recording what
+   happened. (Anthropic: "Claude can fix these conflicts faster than humans can identify
+   them.")
+
+5. **A small team + agents builds substantial systems fast.** Seven humans built a whole
+   VCS plus a review tool in five months. This troupe's lane model is the same shape:
+   many small free agents, one operator, fast landed artifacts. The limit is evidence,
+   not headcount.
+
+6. **Component "superfans."** A dedicated agent obsessively watching one component's
+   health catches subtle, novel failures that threshold alerts miss. Candidate lanes here:
+   a troupe-pipe superfan (checks every check-in/commit/reply against the evidence law)
+   and a forge superfan (Gitea health). Open proposal, not yet staffed.