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.

---

Phase-Specific Prompt Library

For detailed, phase-oriented guardrails that are tightly coupled to CORE’s architecture, invariants, ADRs, and epistemic model, see:

docs/core-rd-base-prompts.md

These prompts are designed to be used as standing prefixes in addition to this file. The "Session Entry / Context Load" prompt is especially recommended at the start of most sessions. The "Standing Loop Axiom Check" is highly effective as a final self-audit before committing.

---

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. Complete the Workspace Hygiene + Branch/Worktree Protocol — confirm project root, inspect dirty state, classify loose files, fetch current refs, establish clean main, and create a fresh worktree for non-trivial work.
5. Run the smoke suite and report pass/fail:

   core test --suite smoke -q
   

   If the local environment does not expose core, report the exact failure and use the repo-native pytest lanes required by the task.
6. 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.
7. 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–6. History does not survive context resets. Ground yourself in the repo.

---

Workspace Hygiene + Branch/Worktree Protocol

Before any edit, branch switch, worktree creation, stash, or commit, establish the repository state. This protocol is mandatory for Grok 4.3 / Grok Build sessions on CORE.

0. Confirm project root

Run:

pwd
git rev-parse --show-toplevel
test -f GROK.md
test -f AGENTS.md

If the current directory is not the repository root, run:

cd "$(git rev-parse --show-toplevel)"

Do not proceed from a parent directory, sibling worktree, nested package directory, or generated-output directory.

1. Inspect local state before touching branches

Run:

git status --short --branch
git diff --stat
git diff --name-status
git diff --cached --name-status
git stash list
git worktree list

If the working tree is dirty, do not switch branches, pull, reset, overwrite, or stash blindly.

Classify every changed or untracked file first:

• Does it belong to the current task?
• Does it appear to belong to a recent branch or PR?
• Is it an accidental generated artifact?
• Is it an evidence/report file that should be restored rather than deleted?
• Is it unknown?

For unknown changes, inspect before stashing:

git diff -- <path>
git log --oneline --decorate --all -- <path>
git branch --sort=-committerdate | head -20
gh pr list --state open --limit 20
gh pr status

If the origin remains unknown, preserve it with a descriptive stash instead of deleting it:

git stash push -m "WIP unknown before <task-slug>: <short file summary>" -- <paths>

Never use git reset --hard, broad git checkout ., broad git restore ., git clean, or destructive cleanup unless the user explicitly approves or every affected file has been classified as disposable.

2. Establish a clean, current baseline

After the tree is clean or unknown work is safely stashed:

git fetch origin --prune
git switch main
git pull --ff-only origin main
git status --short --branch

If main cannot fast-forward, stop and report the exact state. Do not merge, rebase, or resolve conflicts unless explicitly instructed.

3. Prefer a new worktree for non-trivial implementation

For non-trivial runtime, reasoning, eval, teaching, pack, or multi-file work, create a fresh worktree from current origin/main:

git worktree add ../core-<task-slug> origin/main -b <branch-name>
cd ../core-<task-slug>

Use a normal branch in the same worktree only for small docs/config work or when the user explicitly requests it. Do not reuse stale branches for new work unless the task is explicitly a continuation of that branch.

4. Branch naming

Use scope-bounded branch names:

feat/gsm8k-workstream-a-gate-a1-comparative-injection
docs/<area>-<purpose>
fix/<area>-<specific-bug>
chore/<area>-<specific-cleanup>

The branch name should encode the capability slice, not an agent name or vague intent.

5. Completion protocol

Before opening a PR:

git status --short
git diff --check origin/main...HEAD
git diff --name-status origin/main...HEAD
git log --oneline --reverse origin/main..HEAD

Run the relevant focused tests and record exact outputs. For every PR summary include:

• branch name;
• commit list in order;
• exact changed files;
• exact tests/evals run;
• whether wrong_total == 0 applies and held;
• known caveats;
• explicit non-goals;
• handoff content or handoff file path.

---

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.

---

Versor Coherence Guardian Protocol

Before proposing or executing any change that could affect versor closure, field propagation, or exact CGA recall:

1. Explicitly confirm that the core invariant holds: ||F * reverse(F) - 1||_F < 1e-6 for the affected FieldState.
2. Verify that versor_apply(V, F) and cga_inner(X, Y) paths remain exact and untouched except through the allowed modules (algebra/versor.py and permitted callers).
3. Re-run the relevant invariant checks from tests/test_versor_closure.py (or current equivalent) on the modified paths.
4. Only after the above may you proceed with edits or proposals.

This protocol is mandatory for any work in algebra/, field/, vault/, or generate/.

---

NON-NEGOTIABLE INVARIANTS

These are hard architectural constraints enforced by construction. Violating any one of them is a bug that must be reverted before merge.

Versor & CGA Level (Exact Algebraic Coherence)

• ||F * reverse(F) - 1||_F < 1e-6 must hold identically for every runtime FieldState and every application of versor_apply(V, F).
• All state is represented as versors. All transitions are exact versor products. No exceptions, no approximations.
• Multivector representation in algebra/ uses fixed (32,) float32 arrays for Cl(4,1). No dynamic resizing or external library types in the hot path.
• cga_inner(X, Y) = -d²/2 is the sole exact recall primitive. It must remain exact and deterministic.

Normalization & Approximation Boundaries

• Normalization is allowed ONLY at the explicitly listed locations:
  • ingest/gate.py
  • language_packs/compiler.py
  • algebra/versor.py
  • sensorium/*/canonical.py (signal canonicalization, pinned only)
  • session/context.py (semantic anchoring)
• Forbidden everywhere else, including generate/stream.py, field/propagate.py, vault/store.py, and all logging/telemetry paths.

No Approximate or Stochastic Mechanisms

• No cosine similarity, HNSW, ANN indexes, embedding-based recall, or any approximate nearest-neighbor mechanism anywhere in the deterministic cognitive path.
• Vault recall is exact cga_inner only.
• No stochastic generation, sampling, opaque LLM fallbacks, or probabilistic mechanisms in the core deterministic reasoning, teaching, recognition, or realization pipelines.

Claim Schema & Epistemic Rigor

• Claim status transitions (SPECULATIVE → COHERENT → CONTESTED → FALSIFIED) may only occur through the defined review-gated TeachingChainProposal mechanism.
• A claim may not move to COHERENT without passing all applicable review gates and producing a reproducible evidence bundle.
• No direct mutation of epistemic status. Only vault/store.py may transition status (INV-29).
• User-facing vault.recall must enforce min_status=COHERENT (INV-24).

Safety & Identity Packs

• Safety packs (packs/safety/) are unmodifiable at runtime. They are fail-closed and reviewer-signed.
• Identity packs are swappable only via the defined PersonaMotor + proposal mechanism. Runtime mutation is forbidden.
• Any attempt to relax or bypass a safety axis must be rejected and logged as a protocol violation.

If you believe one of these must change for correctness or performance reasons, STOP. Write a proposal in notes/ or docs/decisions/ and do not implement the change. 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 ||F * reverse(F) - 1||_F < 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.

---

Kernel Substrate / ProblemFrame Doctrine

New derivation capabilities must consume KernelFacts / ProblemFrame facts where the substrate can represent the needed meaning (generate/problem_frame_builder.py).

raw problem text → KernelFacts → ProblemFrame → contract-backed derivation organs

New raw-prose/local-regex parsing inside a derivation organ requires an explicit LEGACY_EXCEPTION note and a migration rationale. Guard: tests/test_kernel_no_new_legacy_derivation_surfaces.py.

Do not add isolated benchmark organs with local prose parsers. Do not treat #829 substrate modules as optional helpers.

---

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, and 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 relevant 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.

For runtime/algebra/cognition/teaching/pack changes: run full suite before merge. For docs/config-only agent-governance changes: smoke is sufficient unless the PR touches CLI, tests, generated docs, or executable scripts.

---

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. For runtime/algebra/cognition/teaching/pack changes, run full before merge. For docs/config-only agent-governance changes, smoke is sufficient unless the PR changes CLI, tests, generated docs, or executable scripts.