pipelines/SUBAGENT_CONTRACT.md
What this is. The preamble every fan-out lane inherits, verbatim. A director pastes the block in
§1 into every agent() / Task prompt before the lane's own instructions. It is short on purpose: a
contract nobody pastes is a contract nobody has.
Why it exists. On 2026-08-01 a lane was asked for a Flores concept-art board. It built the board
out of two proposal docs (docs/proposals/CONCEPT_ART_PROGRAM.md,
docs/proposals/REALM_DESIGN_PROGRAM.md) and never opened docs/spine/CH_02.md or
_source/02_Tier_2_Region_Pages/flores_island.md. So it invented a "pick one of three readings of
Flores" frame and asked Josh to re-decide content the spine had already settled — while
docs/spine/CH_02.md line 226, ## Asset anchors, already listed the board's whole contents, typed
and id'd, each bullet tagged [POPULATE→ ...] with its destination registry. It shipped zero images
and about four thousand words of prose. **It passed a structural gate and four adversarial critics
and was still completely wrong**, because nothing anywhere checks that an artifact DERIVES FROM the
canon it claims to realize. This contract is the author-side half of that fix; the gate-side half is
named per work kind in docs/TASK_ROUTER.md.
---
STANDING SUBAGENT CONTRACT (docs/SUBAGENT_CONTRACT.md — binds this lane)
1. CANON IS AUTHORITY. Canon is docs/spine/*.md, _source/01_Tier_1_Foundation/*,
_source/02_Tier_2_Region_Pages/*, and the T0 registries under registries/.
Everything in docs/proposals/ is SUBORDINATE. If a proposal and canon disagree,
canon wins and the proposal is the defect.
2. READ YOUR TARGET'S CANON NODE BEFORE YOU PRODUCE ANYTHING. Run
`python harness/route.py <work-kind> --chapter CH_NN --region <region_id>`
and read the read-set it prints, in the order it prints it. If your work kind
is not listed, say so in your return and name the canon node you read instead
— never substitute a proposal for the node.
3. PROPOSALS ARE HOW, NEVER WHAT. A program doc tells you the order of operations,
the lane routing, the licence posture, the board shape. It never tells you what
the region contains, what the chapter is about, or which creatures are in it.
Canon already answered those. If you find yourself designing a choice between
readings of a place, stop: the spine node has already chosen.
4. CITE file:line FOR EVERY CLAIM. A claim without a citation is a guess and will
be cut. Quote the canon line you are realizing rather than paraphrasing it.
5. DECLARE WHAT CANON YOU REALIZED. Your return opens with a DERIVATION block:
DERIVED FROM:
- docs/spine/CH_02.md § Asset anchors (L226) — bullets: creatures_and_fauna,
architecture_set_dressing, material_palette and style_register
- _source/02_Tier_2_Region_Pages/flores_island.md § Zone Catalog (L38) —
care_tier, asset_routing, meters_per_vertex
- registries/T0_Creature_Roster — CR_0001..CR_0006, CR_0010
NOT DERIVED (authored judgment, and why it had no canon home):
- <line> — <why>
Every produced element traces to a DERIVED line or appears under NOT DERIVED.
An empty NOT DERIVED list is the normal, healthy case. A long one means you
were routed wrong — say so instead of filling it.
If your artifact kind is enrolled in docs/canon_derivation.json, this same
declaration also lands machine-readably in the artifact's own coverage key,
where gate `canon_derivation` reads it: every id canon names is either
`covered` or `pending`, and a `pending` carries its reason and its resolving
destination on the artifact's own face. Never leave an id undeclared — an
undeclared id is the exact shape of the failure above.
6. YOU MAY NOT CHANGE CANON. Not the spine, not region pages, not the CVD, not
registry rows, not numerical/naming/hard-line/§17 content. If your work needs
canon changed, that is a finding for the director, not an edit.
7. DO NOT ASK JOSH TO RE-DECIDE. Before surfacing any question, check the head of
docs/spine/DECISIONS_PENDING_JOSH.md and docs/BATCH1_RULINGS.md. Most things
that feel like decisions are already ruled. If it is genuinely his, run
CLAUDE.md's four-step decision protocol — steelmanned alternatives, deep dive,
adversarial review, then options + pros/cons + a RECOMMENDATION + the strongest
objection. Never a bare question.
8. LAND IT. `python harness/run_gates.py` must exit 0 before you commit; read the
output UNPIPED. Every doc you create or move is registered in docs/DOC_MAP.md
in the SAME commit. Commit; do NOT push — the director pushes.
---
that makes the failure visible in the return rather than three reviews later.
model explicitly on every fan-out. Nothing inherits the session model (standing globalagreement; one 8-agent fan-out once burned ~20% of a weekly limit).
## Asset anchors as item 1 if it had run route.py concept-art-region. Everything else in this contract is downstream of that.
sections and ask "does the artifact realize these, and does it contain anything that is in neither
list?" — a question no critic could ask before, which is precisely why four of them passed a wrong
board. Until the per-work-kind teeth named in docs/TASK_ROUTER.md are built, the DERIVATION block
is the enforcement.
proposal docs. That is the failure, restated in its own words.
---
CLAUDE.md (working agreements) · docs/START_HERE.md (the task-router section) ·
docs/TASK_ROUTER.md (every work kind ends by pointing here) · docs/task_router.json
(contract field, checked by python harness/route.py --self-test, gate router) ·
docs/DOC_MAP.md §2.