core/.github/copilot-instructions.md

CORE Agentic Coding Instructions

Use these instructions for Copilot/Codex-style repository work.

Mission

CORE is a deterministic cognitive engine. The near-term goal is basic teachable cognitive chat:

listen -> comprehend -> recall -> think -> articulate -> learn from reviewed correction -> replay deterministically

Do not treat the repository as a normal chatbot wrapper or transformer project. Do not add hidden LLM fallbacks, stochastic generation, or broad infrastructure that bypasses the geometric cognitive path.

Current Architecture

The cognitive path is centered on:

• core/cognition/pipeline.py
• generate/intent.py
• generate/graph_planner.py
• generate/realizer.py
• teaching/correction.py, teaching/review.py, teaching/store.py
• evals/*
• calibration/*
• language_packs/data/en_core_cognition_v1

The runtime response contract is documented in docs/runtime_contracts.md. Follow it.

Hard Invariants

Runtime field states must satisfy:

versor_condition(F) < 1e-6

Allowed construction/closure sites:

• ingest/gate.py
• language_packs/compiler.py / vocabulary construction
• algebra/versor.py

Forbidden hot-path repair sites:

• generate/stream.py
• field/propagate.py
• vault/store.py
• telemetry/logging shell code

Do not add grade monitors, drift timers, watchdog repair functions, ANN/HNSW, cosine similarity, or approximate recall.

Efficiency and Performance

Treat performance as part of the architecture. Slow feedback causes poor engineering decisions and hides regressions.

When touching hot paths, prefer:

• backend-dispatched algebra when semantics match
• import hoisting and removal of repeated structure-building
• deterministic immutable caches or safe copied data
• exact CGA batching/vectorization instead of approximate search
• small validation lanes and bounded eval cases for iterative work

Do not improve speed by weakening invariants, skipping construction checks, adding hot-path repair, using approximate recall, or mutating shared cached state unsafely.

Security and Trust Boundaries

When touching user-controlled text, dynamic imports, filesystem paths, CLI reports, pack validators, or logs, enforce and test the trust boundary.

Required defaults:

• arbitrary-code execution must be explicit and opt-in
• unsafe pack IDs and path traversal must be rejected
• raw user text should not be leaked in expanded logging unless local/debug is explicit
• pack mutations stay proposal-only unless a reviewed path applies them
• report/file writes must be bounded to caller-specified paths with clear behavior

Surface Contract

Keep these separate:

• surface: selected user-facing response.
• walk_surface: raw generation/manifold evidence.
• articulation_surface: proposition/realizer surface.

Current policy:

surface = articulation_surface
walk_surface = retained telemetry/evidence

Teaching Safety

Learning is reviewed mutation:

• Session memory can be immediate.
• Reviewed memory must use teaching/*.
• Pack mutation is proposal-only until reviewed.
• Identity override attempts are rejected.
• User text cannot mutate identity axes, runtime policy, or operator code.

Validation

Use CLI suites:

core test --suite smoke -q
core test --suite cognition -q
core test --suite teaching -q
core test --suite packs -q
core test --suite runtime -q
core test --suite algebra -q
core test --suite full -q
core eval cognition

For a feature PR, run the smallest relevant suite and then full when practical.

Current Work Sequence

1. Keep CLI lanes and core eval cognition green.
2. Tighten hot-path backend consistency and semantics-preserving performance.
3. Harden pack/OOV/logging trust boundaries.
4. Add exact vault recall indexing/batching without approximate search.
5. Add Rust backend parity only after Python semantics are locked by tests.
6. Expand curriculum teaching after replay/eval/calibration remain deterministic.

PR Standard

Every change should state:

Capability/performance/security boundary added or protected:
Invariant protected:
CLI suite/eval run:
No hidden normalization / stochastic fallback / approximate recall / unreviewed mutation:
Trust boundary enforced when relevant:

Prefer small PRs. Do not combine baseline repair, feature work, and broad reorganization unless unavoidable.