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
• 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.

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

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

PR Standard

Every change should state:

Capability added/protected:
Invariant protected:
CLI suite run:
No hidden normalization / stochastic fallback / unreviewed mutation:

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