diff --git a/skills/agent-graphs/IMPROVE.md b/skills/agent-graphs/IMPROVE.md
index 92269073..29a08090 100644
--- a/skills/agent-graphs/IMPROVE.md
+++ b/skills/agent-graphs/IMPROVE.md
@@ -35,6 +35,14 @@ Holdout discipline: at least 3 of the 8 held out, never trained on; `runImprovem
 - No new optimizer, campaign runner, judge plumbing, or ledger — all named above.
 - No live-backend scoring in the loop. Live runs are pursuit work, not skill-improvement work; the loop stays offline and free.
 
+## Orchestration layering (doctrine, gates gen4)
+
+Two layers, different jobs.
+Foundation harnesses ship trained orchestration — Claude Code subagents, codex goal-mode, pi extensions — and prose is that layer's native API: instructing a claude-code node to "fan out subagents over these files" invokes an in-distribution capability, not vibes.
+The graph/script layer exists for what no single harness provides: cross-harness composition, one conserved budget across the whole tree, durable ledger evidence, resume, and heterogeneous model placement.
+Rule: outer layer coarse, inner layer maximal — one harness-sized node told to use its native fan-out beats N externally-choreographed thin nodes that each pay the harness floor while suppressing the orchestration the model was trained for.
+Which harnesses qualify for native fan-out is a supervisor-lab harness-KB row, not a guess.
+
 ## Version history
 
 The live tree carries only the current `SKILL.md`; every prior surface text is recoverable from git history via the pinned sha256s below, and each generation's full measurement record lives in `generations/`.
diff --git a/skills/agent-graphs/generations/gen3.json b/skills/agent-graphs/generations/gen3.json
index 47329ddb..5d9b6d51 100644
--- a/skills/agent-graphs/generations/gen3.json
+++ b/skills/agent-graphs/generations/gen3.json
@@ -695,7 +695,8 @@
       "author JSON contract aligned with the skill text (remove perWorker.maxIterations or lower it correctly)",
       "holdout refresh: cases authored blind by an agent given only the case schema, never failure history; contaminated comparison retired",
       "persist revision-prompt inputs alongside the sha",
-      "fix in-loop gate wiring so the upstream record is authoritative"
+      "fix in-loop gate wiring so the upstream record is authoritative",
+      "layering doctrine: foundation harnesses ship TRAINED orchestration (Claude Code subagents, codex goal-mode, pi extensions) and prose is its native API \u2014 the graph layer composes ACROSS harnesses (conserved budget, ledger evidence, resume, heterogeneous models), it does not re-choreograph WITHIN one. Outer layer coarse, inner layer maximal: prefer one harness-sized node instructed to use its native fan-out over N externally-choreographed thin nodes. The unmeasured-harness case expectation (nodes=3) and v3's held N-roles-N-nodes lesson are both suspect under this rule; gen4 needs a case whose correct answer is one node + native-fanout instruction, and the harness KB row decides which harnesses qualify"
     ]
   }
 }