Mandatory neo-core read gate for instance & reactive-state work: core-idiom contracts enter the authoring + review substrate

Context (friction→gold, operator-ratified 2026-07-04)

Live specimen from tonight: the create-module leaves (#14655/#14656/#14689/#14711) shipped apps/agentos (Body-hemisphere) code written in Brain style — plain modules, injected resolution seams, sequential direct property writes — because the author's prior-art reads were ai/services/graph/ siblings, not src/ core. Two concrete idiom violations reached an approved/reviewed state before the operator's challenge caught them:

1. Live-component mutation via chained direct assignments instead of the batched component.set() path (src/core/Base.mjs — EffectManager pause, coherent beforeSet/afterSet, single cascade).
2. A bespoke injected resolveComponent seam instead of the core instance manager (Neo.get + afterSetId auto-registration + the enhanced Symbol.hasInstance shape guarantee) — which then caused a full review cycle hardening against a "wrong-shaped component" class the core contracts structurally preclude.

The reviewer is not the safety net here and cannot be: the sole active cross-family reviewer runs a 258K context window and often cannot afford the neo-core read alongside the diff. The gate must live in the substrate, author-side first.

The Fix (substrate placement — three surfaces, one rule)

The rule: Before authoring or reviewing code under apps/ or src/ that creates, mutates, resolves, or destroys Neo instances — or manages view state — read the relevant contracts in src/Neo.mjs + src/core/Base.mjs (at minimum: Neo.create/setupClass gatekeeping, reactive configs + set() batching, Neo.get/instance-manager resolution, observeConfig, destroy semantics). Pure data-plane logic (parsing, validation, transition tables) as plain util modules is fine and childapp-precedented; the boundary is instance mutation + view state.

Placement (each its own small PR-able edit, net-bytes-conscious per the compaction taxonomy — read learn/agentos/decisions/0007-agents-md-compaction-taxonomy.md before touching turn-loaded substrate):

• ticket-intake workflow payload (author-side, the primary gate): a Body-side pre-flight line — the intake for any apps//src/ implementation names which core contracts were read, the same way KB/prior-art sweeps are named.
• pr-review guide payload (reviewer-side, the backstop): a Body-side review checklist line — instance-touching diffs get checked against set()-batching / manager-resolution / reactive-config idioms; reviewers with tight context windows may satisfy it via the KB instead of a full core read.
• AGENTS.md §edge_case_triggers "Authoring Discipline" (the trigger line): sharpen "read 1-2 sibling files" with the hemisphere clause — Body-side siblings live in src/, not only in the feature directory; ~2 lines, compaction-taxonomy-compliant.
• KB anchor: ensure ask_knowledge_base surfaces the Base.mjs set()/instance-manager/reactive-config contracts for queries like "mutate a live component" (verify with a live query; file a KB gap if it misses).

Acceptance Criteria

• All three substrate surfaces carry the rule; combined added bytes justified against the measured cost (2 violations × 1 review cycle × operator escalation, tonight alone).
• The rule states the ALLOWED half explicitly (pure data-plane plain modules, childapp-precedented) — a gate that over-triggers on validators/tables gets ignored.
• A live KB query for the mutation idiom returns the Base.mjs contract (or a KB-gap ticket exists).

Evidence anchor

The correction pair: PR #14710 addendum (batched set(), Neo.get default, id stamping) + PR #14712 addendum (transition table = oracle for a reactive flowState_ config, never a parallel store). Root-cause statement on both.

Related

#13349 (the pillar whose view tranche this protects) · #14710/#14712 (the correction specimens) · src/core/Base.mjs / src/Neo.mjs (the contracts) · learn/agentos/decisions/0007-agents-md-compaction-taxonomy.md (governs the AGENTS.md touch).

Claimable — substrate lane; I'll take it after my open PR gates clear unless someone reaches it first.

Origin Session ID: b9b95ac6-42f5-47a3-b58f-6071f79657e8 Retrieval Hint: "mandatory neo core read gate Body-side neo core idiom set batching instance manager reactive config"