core/GROK.md

CORE Agent Instructions for Grok 4.3

Read this file in full before touching any file in this repository. CORE is a deterministic cognitive engine — not a transformer wrapper, not a generic chatbot, not an infrastructure playground. The rules here are architectural invariants, not suggestions.

You are stateless. You have no memory of prior sessions. Complete the Session Start Checklist before any edits. Do not skip it.

---

Session Start Checklist

Run these steps in order, using your tool-call chains, before writing a single line of code:

1. Read this file in full.
2. Read AGENTS.md in full.
3. Read docs/runtime_contracts.md in full.
4. Run the smoke suite and report pass/fail:

   core test --suite smoke -q
   

5. Check for a recent handoff doc — if a HANDOFF-*.md file exists dated within the last 3 days, read it. It contains state you would otherwise have no way to recover.
6. State your task scope — before editing, write one sentence naming the module(s) you intend to change and the invariant you will prove was not violated.

Do not treat conversation history as a substitute for steps 1–5. History does not survive context resets. Ground yourself in the repo.

---

Reasoning Effort Requirement

You must operate at high reasoning effort for all tasks that touch:

• algebra/
• field/
• generate/realizer.py, generate/graph_planner.py, generate/intent.py
• vault/store.py
• calibration/
• core/cognition/
• teaching/

If you were invoked at default or low effort and the task touches any of these modules, stop and request re-invocation at high effort. Low-effort reasoning on the algebra/field layer produces plausible-looking but mathematically incorrect results.

For workbench-ui/, docs/, notes/, scripts/ at low risk, medium effort is acceptable.

---

NON-NEGOTIABLE INVARIANTS

These are not guidelines. Violating any one of them is a bug that must be reverted before merge.

❌  versor_condition(F) < 1e-6 must hold for every runtime field state F.
    → algebra/versor.py::versor_condition() is the check.  Fix the operator
      path or construction boundary; do not weaken the threshold.

❌  Normalization is allowed ONLY at:
      ingest/gate.py
      language_packs/compiler.py
      algebra/versor.py
      sensorium/*/canonical.py  (signal canonicalization, pinned only)
      session/context.py        (semantic anchoring; see CLAUDE.md for exact rule)
    Forbidden everywhere else, including generate/stream.py, field/propagate.py,
    vault/store.py, and all logging/telemetry paths.

❌  No cosine similarity, HNSW, ANN indexes, or approximate recall anywhere
    in the runtime path.  Vault recall is exact and deterministic.

❌  No stochastic generation, opaque LLM fallbacks, or sampling in the
    deterministic cognitive path.

❌  No pack mutation outside the proposal-only reviewed teaching loop.

❌  INV-21: only allowlisted modules may call VaultStore.store(...).
❌  INV-22/23: unmarked pack rows and store() defaults are SPECULATIVE.
    COHERENT requires an explicit stamp.
❌  INV-24: user-facing vault.recall must pass min_status=COHERENT.
❌  INV-29: only vault/store.py may transition epistemic_status.
❌  INV-30: open-world determine() constructs Determined(answer=True) or
    refuses; it never asserts answer=False.

If you believe one of these must change, stop. Write a proposal in notes/ and do not implement it. CORE's architecture is not negotiated inside a coding session.

---

Pre-Edit Sweep Protocol

Before editing any module in algebra/, field/, generate/, vault/, core/cognition/, teaching/, or calibration/:

1. Use your file-read and search tool chains to trace every import of the target module across the codebase.
2. Identify all callers of the specific function or class you intend to change.
3. Check calibration/ and evals/ for tests that exercise the changed path.
4. Only then propose edits.

Your 1M-token context window means you can load the full relevant subgraph in one pass. Do this. Do not guess at call sites.

---

Agentic Tool-Call Discipline

Grok 4.3's multi-step tool-call chains are an asset here. Use them to:

• Load the full affected module graph before proposing changes.
• Run CLI validation lanes and report actual output, not assumed output.
• Confirm invariants are held after edits by re-running the relevant suite.

Do not use tool chains to:

• Probe for statistical or ML-based workarounds to exact CGA constraints.
• Discover "alternative" normalization sites not listed above.
• Chain edits across multiple modules before verifying the first one.

---

Arena / Parallel Subagent Mode

If running in Arena mode (parallel subagents):

• Each subagent receives its own copy of this file and AGENTS.md.
• Each subagent must independently satisfy versor_condition < 1e-6 before reporting results.
• Do not share mutable runtime state between subagents.
• Treat Arena subagent results as independent proposals, not sequential commits. Reconcile them before any merge.
• No subagent output becomes another subagent's unchecked input.

---

End-of-Session Handoff Requirement

At the end of every session, write a handoff document to the repo using the template at docs/handoff_template.md. Name it:

HANDOFF-grok43-YYYY-MM-DD.md

This is not optional. It is the only continuity mechanism across your stateless sessions. A session without a handoff doc is a session whose work may be silently lost or contradicted by the next session.

---

Architecture Summary

Raw input becomes a closed versor field once; thought evolves through exact versor transitions and CGA recall; cognition is structured as intent, proposition graph, articulation target, deterministic realization, reviewed memory, eval/calibration replay, and traceable evidence.

CognitiveTurnPipeline
  -> tokenize / OOV policy / inject
  -> intent classification
  -> PropositionGraph
  -> ArticulationTarget
  -> deterministic realizer / articulation surface
  -> generation walk telemetry
  -> identity + energy telemetry
  -> reviewed teaching capture (when correction intent appears)
  -> deterministic trace hash

Key modules:

• core/cognition/pipeline.py — cognitive turn spine
• core/cognition/result.py — canonical turn result shape
• core/cognition/trace.py — deterministic trace hashing
• generate/intent.py — deterministic intent classification
• generate/graph_planner.py — proposition graph and articulation target
• generate/realizer.py / generate/templates.py — deterministic realization
• teaching/* — reviewed teaching / correction lifecycle
• vault/store.py — epistemic store with INV-21/22/23/24/29 guards
• evals/* — deterministic eval harness
• calibration/* — bounded replay-based calibration
• docs/runtime_contracts.md — runtime response, memory, identity, testing

---

PR Checklist

Before opening or merging, answer:

What capability, performance property, or security boundary did this add/protect?
Which invariant proves the field remains valid?
Which CLI suite/eval proves the lane?
Did this avoid hidden normalization, stochastic fallback, approximate recall,
  and unreviewed mutation?
If it touches user input, files, dynamic imports, or logs, what trust boundary
  was enforced?
Was the smoke suite green before and after?

Prefer small, load-bearing PRs.

---

CLI Validation Lanes

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

Run the smallest relevant suite first, then full before merge.