Substrate First

Substrate-First — DRY gate + drift audit

The workspace — 18 repos carrying a root BOUNDARY.md as of 2026-09-01, derived by the snippet in Step 2 rather than typed here — has a recurring failure mode: an agent receives a task ("add threat perception"), jumps to implementation without checking existing substrate, and builds a parallel system that duplicates functionality already shipped under a different name. The user then has to catch it manually.

This skill prevents that. It runs in two modes:

1. Pre-implementation gate — run BEFORE writing code
2. Existing-code audit — scan for already-shipped DRY violations

Canonical failures (the pattern this skill prevents)

Failure 1 — ThreatField (Issue 047, riir-mmorpg-examples, 2026-08-01)

Built: ThreatField — a spatial hash grid (HashMap<(i32,i32), u32>) for threat perception. Deposited monster positions into cells; NPCs sampled the 3×3 neighborhood.

Already existed: GenericSpatialBelief<T> + target_within_visible_radius()

• decay_confidence() — the full fog-of-war → belief → decay pipeline in riir-games-shared/src/game_traits/spatial.rs.

Why the grep missed it: The agent searched for "threat field" / "spatial hash". The substrate ships as GenericSpatialBelief / SpatialBelief / confidence_decay. A single-vocabulary grep returns ZERO hits even when the substrate fully exists.

Resolution: Reverted. The plain scan (tick_swarm_emotions) is a simpler POC-scale simplification. The belief-based system is deferred until fog-of-war becomes a gameplay feature.

Failure 2 — Orchard + Motivation in SDK src/ (Issue 490 + Issue 493)

Built: NpcReasonSystem, AppleGrowSystem, OrchardGoal, EmotionField, EmotionAxis, tick_feeling_brain directly in the SDK facade's src/.

Already existed: The boundary rule (riir-game-sdk/AGENTS.md) says "no game logic in src/" + Proposal 019 excludes emotion from the SDK. The substrate belongs in riir-games (in riir-ai).

Why the grep missed it: The agent didn't check whether the types violated the domain classification rule (latent semantic emotion ≠ raw physical vocabulary).

Resolution: Extracted to riir-games (orchard) and riir-games::motivation (emotion). The SDK re-exports them.

Mode 1: Pre-implementation gate (BEFORE writing code)

Run this checklist before implementing ANY of these:

• New impl System or tick function
• New trait + impl (perception, cognition, emotion, state management)
• New spatial query / index / hash / grid
• New vocabulary type / DTO / config struct
• New "helper" function that does math (distance, sigmoid, projection)
• New pipeline (perception → emotion → behavior, freeze → sync → thaw)

Step 1 — Vocabulary-translate your search

The concept you're building probably already exists under a different name. Before grepping, write down 3+ name variants for the concept:

This is the same technique as the paper→code vocabulary translation in AGENTS.md §"Manifold Geometry". The R296 canonical failure applies internally too: a concept-name grep returns zero hits because the math ships under operator names.

Step 2 — Grep the CODEBASE (not just docs)

# Grep ALL repos for the substrate names from Step 1.
# Use multiple variants — the concept may exist under any of them.
#
# DERIVE the repo set; never type it (fixed 2026-09-01 — the hard-coded
# 7-repo brace list this replaced could not see 13 of the 20 contract repos,
# INCLUDING two product-set ones: riir-armageddon consumes
# `GenericSpatialBelief` in 2 files that the canonical DRY grep was structurally
# unable to find, and riir-dapps was equally invisible. A gate that cannot see a
# repo cannot tell you whether it consumes substrate or duplicates it.)
cd /Users/katopz/git
grep -rn 'GenericSpatialBelief\|SpatialBelief\|confidence_decay' \
    --include='*.rs' --exclude-dir=target --exclude-dir=.git \
    $(ls -d */ | while read -r d; do
        [ -f "$d/BOUNDARY.md" ] && [ -d "$d/.git" ] && printf '%s ' "$d"
      done)

Three deliberate details, each measured on this pattern (2026-09-01):

Net: 227 hits in 1.4 s vs the old form's 221 in 23 s — strictly wider coverage, no worktree duplicates, 16× faster.

# Also grep .research/ and .proposals/ for design rules that apply:
grep -rn 'two-brain\|fog-of-war\|domain classification\|sync boundary' \
    /Users/katopz/git/*/.{research,proposals,docs}/ 2>/dev/null

If you find existing substrate → STOP. Consume it. Do not build a parallel system. Document why you're consuming it (in the plan/issue).

Step 3 — Check AGENTS.md architectural rules

Before building, verify your design doesn't violate these:

If your design violates any of these → STOP. File an issue. Rethink.

Step 4 — Decide: consume vs. build

Never build new substrate inside a consumer. The consumer provides data + wiring only. If you're writing loops/math/constants in a consumer's src/ → you're building substrate in the wrong place.

Step 5 — Record the decision

In the plan/issue, document:

## Substrate check (substrate-first skill)
- Searched for: [concept names + variants]
- Found: [existing substrate or "none"]
- Decision: [consume / extend / build new]
- Architectural rules checked: [list which rules apply + verdict]

Mode 2: Existing-code audit (scan for drift)

Run this when reviewing code, when you suspect a parallel system, or quarterly as a DRY-hygiene gate (alongside boundary-guard).

Audit Step 1 — Inventory substrate primitives

For each domain, identify what substrate exists:

# Perception / spatial cognition
grep -rn 'GenericSpatialBelief\|SpatialBelief\|target_within_visible_radius' \
    --include='*.rs' /Users/katopz/git/*/  | grep -v '/tests/' | grep -v '/target/'

# Emotion / affect
grep -rn 'EmotionField\|EmotionAxis\|tick_feeling_brain\|AffectField\|DriveSpecSet' \
    --include='*.rs' /Users/katopz/git/*/

# State sync
grep -rn 'SyncBlock\|ZoneDelta\|PlayerStateCache\|GossipDelta\|SyncRegistry' \
    --include='*.rs' /Users/katopz/git/*/

# Spatial
grep -rn 'SpatialIndex\|GridSpatialIndex\|OctreeSpatialIndex\|MapPos3D' \
    --include='*.rs' /Users/katopz/git/*/

Audit Step 2 — Grep for parallel systems

For each substrate primitive found in Step 1, grep consumer code for reimplemented versions.

Derive the consumer set — this block hard-coded {riir-mmorpg-examples,riir-game-sdk} until 2026-09-01 and so could see 2 of the 20 contract repos. That is the same defect the vocabulary step above was fixed for, in the same file, one section down: 60655c48 corrected the Step 2 named "Step 2" and left this one, which is the step that actually looks for duplicate implementations. riir-armageddon — a product-set repo that consumes GenericSpatialBelief in 2 files (6 sites) — was invisible to every grep below.

cd /Users/katopz/git
consumers() {
  ls -d */ | while read -r d; do
    [ -f "$d/BOUNDARY.md" ] && [ -d "$d/.git" ] && printf '%s ' "$d"
  done
}
# Look for inline distance math (should use MapPos3D methods):
grep -rn '(dx.*dx.*dy.*dy).*sqrt\|distance_2d.*fn\|fn.*distance' \
    --include='*.rs' --exclude-dir=target --exclude-dir=.git $(consumers)

# Look for inline sigmoid/exp (should use substrate sigmoid or tick_feeling_brain):
grep -rn '1\.0\s*/\s*(1\.0\s*\+\|sigmoid\|exp(' \
    --include='*.rs' --exclude-dir=target --exclude-dir=.git $(consumers)

# Look for HashMap-based spatial structures (should use SpatialIndex substrate):
grep -rn 'HashMap.*i32.*i32\|spatial.*hash\|cell.*grid' \
    --include='*.rs' --exclude-dir=target --exclude-dir=.git $(consumers)

# Look for parallel belief/perception types (should use GenericSpatialBelief):
grep -rn 'struct.*Belief\|struct.*Perception\|struct.*Visibility\|last_known' \
    --include='*.rs' --exclude-dir=target --exclude-dir=.git $(consumers)

# Look for parallel emotion types (should use EmotionField/AffectField):
grep -rn 'struct.*Fear\|struct.*Mood\|struct.*Emotion\|fear.*f32' \
    --include='*.rs' --exclude-dir=target --exclude-dir=.git $(consumers)

Audit Step 3 — Classify findings

For each hit, classify:

Audit Step 4 — Report

Summarize findings:

## Substrate-first audit (date)
### Substrate inventory
- [domain]: [primitive] at [location]
### Findings
- [file:line] — [classification] — [description]
### Clean
- [domain] — no violations found

The vocabulary-translation defense (why this skill exists)

The hardest failures to catch are the ones where the substrate exists but ships under a name that doesn't match the concept you're searching for. This is the R296 canonical failure (documented in AGENTS.md §"Manifold Geometry"), applied internally:

You think: "I need a threat field"
You grep:   "threat field" / "spatial hash"  → 0 hits
Substrate:  GenericSpatialBelief + decay_confidence  → exists, fully functional

You think: "I need emotion decay"
You grep:   "emotion decay" / "fear fade"  → 0 hits
Substrate:  tick_feeling_brain + DecayRates + EmotionBaseline  → exists

You think: "I need state persistence"
You grep:   "save state" / "persist"  → 0 hits
Substrate:  LocalKvStore + freeze_avatar_delta + ShardIndex  → exists

The defense: always search 3+ vocabulary variants. The translation table in Mode 1 Step 1 is the canonical reference. Extend it when you discover new mismatches.

When NOT to use this skill

• Pure refactoring that doesn't add new concepts (renaming, reorganizing)
• Bug fixes in existing code (the substrate is already consumed or not)
• Test-only code (tests can define inline helpers)
• Build/config changes (Cargo.toml, scripts)

Relationship to sibling skills

substrate-first is upstream of boundary-guard: if substrate-first catches the drift before it ships, boundary-guard has nothing to find. They're complementary — substrate-first is the prevention, boundary-guard is the cure.

Filing violations

When the audit finds a DRY violation or parallel system:

1. File an issue in the repo where the violation lives
2. Reference this skill + the substrate it duplicates
3. Include the vocabulary translation (what you searched for vs. what the substrate is actually called)
4. Propose the fix (consume substrate / extract to substrate / revert)
5. Classify (POC simplification vs. DRY violation vs. architectural violation)

Do NOT fix in the same commit as detection — separate detection from fix so other agents can review the violation independently.

Run log

Compacted 2026-09-11 (user-directed verbose-history pass; the file was 74 KB). Rows carried full verification narratives until this compaction; git log -p -- .agents/skills/substrate-first/SKILL.md recovers any of them verbatim (git log -S '<date>' -- <this file> for one row). New rows append ONE line each.

Standing lessons (distilled from the compacted rows — load-bearing audit classes)

• Body-read before filing a sigmoid/def hit. A local fn sigmoid that DELEGATES to katgpt_core (e.g. a ±50-clamp wrapper) is the SANCTIONED delegation pattern (ndb Issue 611's own fix shape; riir-auth session.rs; chain runtime.rs) — a definition-grep hit is a lead, not a finding. Corollary: katgpt_core::sigmoid is Cephes (~1 ULP), NOT bit-identical to libm-exp forms — delegation is a semantic change where bit-exactness is committed (freeze-commitment paths carry a version-boundary caveat).
• Documented false-positive classes for distance/sqrt greps: squared-distance comparisons (dx*dx+dy*dy <= r*r — the CORRECT no-sqrt idiom; "fixing" it is a pessimization); wire/snapshot [f32;N] DTO operands (no MapPos3D to delegate); grid-space heightfield math; statistical/financial sqrt (std-dev, AMM LP checked_sqrt); disc radial sampling (r*sqrt(u)); screen-space view-plane placement; #[cfg(test)] sites; closed-form test oracles (PSD max-eigenvalue).
• Copy-gate convention: a justified copy needs in-source rationale + a divergence-failing test (chain Issue 139 — a doc-only mirror with only self-consistency tests is NOT enough). Documented copy families: BLAKE3(pubkey)[..16] (5 gated instances — consolidate the 6th onto riir_wallet_signer::player_id_hash); splitmix64 finalizer (~20 substrate-side module-locals, all bit-identical — consolidate at the 4th CONSUMER-side arrival, currently 1); cross-repo message formats single-source by IMPORT (dapps imports chain's canonical signing_message).
• Feature-isolated local math is REQUIRED, not drift — when the feature pulls no katgpt-core (chain forensic f64, congestion inline, the lora bridge keeping katgpt out of the Docker context). Production-dead surface carrying latent duplication under an available dep → delegate-or-prune when consumers materialize (curator_bridge class).
• Translate CRATE names too, not just type/fn names — mmorpg vs riir-games-mmorpg missed a substrate consumer the issue itself cited (Issue 870: the proposed additive StatMods was refuted by the EXISTING clamped StatModifier, Plan 411).
• $(var) executes a command named by the variable — the repo-set helper must be a shell FUNCTION called as $(consumers), or the grep silently scans the whole tree.
• Sanctioned model-consumer shapes (not drift): injected-verifier traits (GmSignatureVerifier pattern); parameterized general form + env-toggle special case (quest_center "one filter home"); feature-neutral placement for gate-union decoupling (HeroStats); Arc<AtomicU8> config seams; two-brain occlusion divergence between substrate and chain verifier (AOI — symmetry pinned on the CHAIN type); plane-split crypto with a hard pub(crate) bar + documented nonce-tradeoff rationale (ndb CLI seal/unseal).