core-labs/core
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: consolidate agent architectural governance into AGENTS.md

Browse source 
This change removes duplicate provider-specific rules across CLAUDE/GPT55/GROK files and replaces them with thin, provider-neutral shims that point back to the canonical AGENTS.md for all architectural invariants, PR discipline, and trust boundaries.
This commit is contained in:
Shay 2026-06-30 10:54:53 -07:00
parent c6263f5a91
commit 63464144c5
5 changed files with 186 additions and 1288 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

409
AGENTS.md
View file

@ -1,39 +1,26 @@
# CORE Agent Instructions
This repository is building a deterministic cognitive engine, not a transformer
wrapper and not a demo chatbot. Every agent must preserve the geometric
runtime while moving the system toward teachable cognitive chat.
This is the canonical governance file for this repository.
## Agent-Specific Instruction Files
If any provider-specific file (`CLAUDE.md`, `GEMINI.md`, or future agent files) overlaps with this document, `AGENTS.md` wins. Provider files should only contain minimal startup and workflow notes, not alternate architecture or alternate invariants.
Different agents read a supplementary file alongside this one. Read yours
before touching any code:
## Mission
| Agent | Supplementary file | Key differences |
|---|---|---|
| **Claude** | `CLAUDE.md` | Deep context; self-restraining; read for semantic anchoring rule nuance |
| **Grok 4.3 + Grok Build** | `GROK.md` | Stateless; requires high reasoning effort; mandatory workspace hygiene; Arena/parallel subagent rules; Plan Mode preferred; skills system; see also docs/core-rd-base-prompts.md for phase-specific prompts |
| **GPT-5.5 (o3-class)** | `GPT55.md` | Stateless; fluency cautions; extended thinking for algebra/field work |
CORE is a deterministic cognitive engine under construction.
If you are Grok 4.3 or GPT-5.5, complete the Session Start Checklist in your
file before reading anything else in this file.
It is:
- inspectable
- replayable
- evidence-governed
- coherence-first
## Grok 4.3 / Grok Build Hard Stops (Mastery Level)
It is not:
- a transformer wrapper
- a generic chatbot
- an infrastructure playground
- a stochastic fallback shell
These apply to Grok 4.3 and Grok Build in addition to every rule below:
1. **You are stateless.** Read `GROK.md` in full, `docs/runtime_contracts.md`, and the most recent `HANDOFF-*.md` (if dated within 3 days) before any edits.
2. **Workspace hygiene is mandatory.** Before branch movement or edits, confirm cwd/repo root, inspect dirty state, classify loose files, fetch/prune, establish clean current `main`, and use a fresh worktree for non-trivial implementation.
3. **High reasoning effort is mandatory** for all tasks touching `algebra/`, `field/`, `generate/realizer.py`, `generate/graph_planner.py`, `generate/intent.py`, `vault/store.py`, `calibration/`, `core/cognition/`, or `teaching/`.
4. **Use Plan Mode** (Grok Build) for any non-trivial change in the above modules. Direct edits are discouraged.
5. **Skills are the preferred mechanism** for repeated protocols. Use `/core-bootstrap`, `/versor-coherence-guardian`, `/pre-edit-sweep`, and `/claim-proposal-guardian` (or their auto-triggered versions).
6. **Sweep before you edit.** Use tool-call chains to trace imports and call sites.
7. **Write a handoff doc at session end** using `docs/handoff_template.md`.
8. **Arena / parallel subagents:** each subagent independently satisfies `||F * reverse(F) - 1||_F < 1e-6` before reporting. Reconcile results before any merge. No mutable state sharing.
---
## North Star
## North star
CORE should become capable of:
@ -41,241 +28,135 @@ CORE should become capable of:
listen -> comprehend -> recall -> think -> articulate -> learn from reviewed correction -> replay deterministically
```
The current path is intentionally staged:
The live path is:
1. Maintain algebra/runtime invariants.
2. Use `CognitiveTurnPipeline` as the spine.
3. Classify intent and build proposition graphs.
4. Plan articulation targets and realize them deterministically.
5. Capture reviewed teaching corrections safely.
6. Seed compact semantic packs for cognition vocabulary.
7. Evaluate through CLI lanes, not ad hoc test fragments.
8. Calibrate bounded operators only from replayable evidence.
```text
CognitiveTurnPipeline
-> tokenize / OOV policy / inject
-> intent classification
-> PropositionGraph
-> ArticulationTarget
-> deterministic realizer / articulation surface
-> telemetry / trace
-> reviewed teaching capture when applicable
-> deterministic replay / eval / calibration
```
Do not skip ahead by adding opaque models, stochastic generation, or broad
infrastructure that hides whether CORE itself is improving.
Improve CORE by strengthening this path, not by bypassing it.
## Philosophical and Architectural Stance
Truth is coherent. CORE's work is to preserve coherent structure from input to
field state to articulation to memory. Treat identity, truthfulness, and
replayability as architectural commitments rather than prompt preferences.
The system's intelligence should come from inspectable geometric state,
structured propositions, deterministic recall, reviewed teaching, and bounded
calibration. Avoid nihilistic or purely statistical framing in code comments,
agent plans, and docs. Prefer responsibility, provenance, and stable meaning.
## The Hard Field Invariant
## Non-negotiable invariants
### Field invariant
Every runtime field state `F` must satisfy:
```text
versor_condition(F) < 1e-6
```
This is checked by `algebra/versor.py::versor_condition()`.
Do not weaken this threshold to make code or tests pass.
Fix the operator or construction boundary that violated it.
If a propagation path violates this invariant, fix the operator path or the
explicit algebra/construction boundary that owns the transition. Do not hide
violations by changing tests, silently weakening thresholds, or normalizing in
hot-path modules.
## Normalization and Closure Rules
Allowed closure/construction boundaries:
- `ingest/gate.py` for raw prompt injection.
- `language_packs/compiler.py` / vocabulary construction.
- `algebra/versor.py` where algebraic sandwich output closure belongs.
Forbidden hot-path repair sites:
### Allowed normalization boundaries
Normalization / closure / canonicalization belongs only at explicit construction or algebra boundaries, such as:
- `ingest/gate.py`
- `language_packs/compiler.py`
- `algebra/versor.py`
- `sensorium/*/canonical.py`
- `session/context.py` for session-scoped **semantic anchoring** of the field toward the session concept-attractor (the anchor pull, hemisphere consistency). Allowed ONLY because every such op (1) preserves `versor_condition` BY CONSTRUCTION — composed from `rotor_power` / `word_transition_rotor` / `versor_apply` on the Spin manifold, never a post-hoc `unitize`/grade-projection — AND (2) carries semantic meaning in the cognitive model.
- other explicitly documented construction boundaries
Forbidden in hot paths and repair layers, including:
- `generate/stream.py`
- `field/propagate.py`
- `vault/store.py`
- runtime telemetry/logging layers
- logging / telemetry / shell glue
Do not add normalization, unitization, grade projection, drift monitors, repair
timers, or watchdog functions outside a documented construction/algebra boundary.
If you think you need one, an upstream operator is unclosed.
**The bright line — semantic anchoring vs. drift repair.** An op is *semantic anchoring* (allowed at the sites above) iff it preserves `versor_condition` by construction AND expresses a relation in the cognitive model. It is *drift repair* (forbidden) iff its purpose is to restore a numerical invariant a prior function should have preserved. Closure of field transitions is owned solely by `algebra/versor.py` (`_close_applied_versor`); no other site may "fix" it. Naming must not disguise the distinction: an op that anchors semantically must not be named or documented as a "drift fix".
CGA null vectors are geometric points and must remain null. Do not force null
vectors into unit-versor closure.
Do not add drift repair, watchdog normalization, hidden unitization, or post-hoc algebra fixes outside owned boundaries.
## The Two Core Primitives
### Exact recall
Runtime recall remains exact and deterministic.
Do not add:
- cosine similarity
- ANN / approximate nearest neighbor
- HNSW
- embedding ranking as runtime memory truth
Field transition:
Use exact CGA recall primitives only.
```text
algebra/versor.py::versor_apply(V, F) -> V * F * reverse(V)
```
### No opaque fallback cognition
Do not add stochastic generation, hidden LLM fallback logic, or probabilistic substitutes inside the deterministic cognitive path.
Distance/recall metric:
### Teaching and mutation safety
Learning is controlled mutation.
- session memory may be local and immediate
- reviewed/durable memory goes through the teaching path
- pack mutation is proposal-only until reviewed
- identity override attempts are rejected, not learned
```text
algebra/cga.py::cga_inner(X, Y)
```
Do not invent a parallel learning path.
Do not add ANN, HNSW, cosine similarity, approximate nearest-neighbor recall,
or non-CGA ranking to runtime memory. Vault recall is exact and deterministic.
#### The learning boundary is typed, not "everything is proposal-only"
A common misreading treats *all* learning as proposal-only. That is a false bottleneck. The real boundary is between **durable** standing and **provisional** standing, and it is already mechanically enforced:
- **Durable mutation stays reviewed or proof-carrying.** Corpus / pack / policy / identity changes, and any promotion to COHERENT/verified standing, go through the reviewed teaching loop (`teaching/*`, proposal-only) or the proof-carrying promotion gate.
- **Provisional state may update autonomously — iff typed, isolated, replayable, and unable to masquerade as ratified truth.** This covers session memory, sealed practice ledgers, SPECULATIVE idle consolidation of soundly-derived facts, reliability-ledger counts, proposal emission, and disclosed licensed estimates. Each is written SPECULATIVE (never COHERENT), through the same `VaultStore.store` path (no parallel memory), deterministically, and carries its standing honestly.
## Current Runtime/Cognition Shape
This boundary is a set of failing-when-violated invariants, not a convention:
- **INV-21** — only allowlisted modules may call `VaultStore.store(...)`.
- **INV-22 / INV-23** — an unmarked pack row and an unmarked `store()` default to SPECULATIVE; COHERENT requires an explicit stamp.
- **INV-24** — every `vault.recall` callsite is categorized; user-facing evidence must pass `min_status=COHERENT`.
- **INV-29** — only `vault/store.py` may transition an `epistemic_status`.
- **INV-30** — the open-world `determine()` gear constructs only `Determined(answer=True)` or refuses; it can never assert `answer=False`. Closed-world entailed-negation must use a distinct closed-world type and entry point.
The live cognitive path is now:
### Kernel substrate rule
New derivation work should consume `KernelFacts` / `ProblemFrame` where the substrate can represent the meaning.
Do not introduce new local prose parsers inside derivation organs unless explicitly marked as legacy exception with migration rationale.
```text
ChatRuntime / 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
```
## Working doctrine
Important modules:
Before editing:
1. Read this file.
2. Read `docs/runtime_contracts.md`.
3. Read the latest recent `HANDOFF-*.md` if relevant.
4. Confirm repo root and inspect working tree state.
5. Run the smallest relevant validation lane.
- `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 planning.
- `generate/realizer.py` / `generate/templates.py` — deterministic realization.
- `teaching/*` — reviewed teaching/correction lifecycle.
- `language_packs/data/en_core_cognition_v1` — compact cognition seed pack.
- `evals/*` — deterministic cognition evidence harness.
- `calibration/*` — bounded replay-based operator calibration.
- `docs/runtime_contracts.md` — runtime response, memory, identity, and testing contracts.
For non-trivial edits:
- trace imports and call sites first
- identify the invariant being protected
- prefer semantics-preserving cleanup before new mechanisms
- keep changes small and load-bearing
- If working in Arena/parallel subagent mode, each subagent must independently satisfy `versor_condition` and results must be reconciled before merge. No subagent output becomes another subagent's unchecked input.
## Efficiency and Performance Doctrine
### Workspace Hygiene + Branch Protocol
Before branch movement or edits:
- Confirm cwd/repo root.
- Inspect dirty state (`git status`, `git diff`); classify loose files before stashing or deleting.
- Establish a clean current `main`.
- Prefer a fresh worktree from `origin/main` for non-trivial implementation.
Performance is an architectural property. Do not treat it as an afterthought
that will be cleaned up after features land.
### Pre-Edit Sweep & Versor Coherence Guardian Protocol
Before modifying any module in `algebra/`, `field/`, `vault/`, or `generate/`:
- Trace every import of the target module and identify all callers.
- Check `calibration/` and `evals/` for tests that exercise the changed path.
- Explicitly confirm the core invariant `||F * reverse(F) - 1||_F < 1e-6` holds for the affected state.
Before modifying hot paths, identify whether the change touches:
## Documentation Discipline
- algebra backend dispatch (`algebra/backend.py`)
- versor application / closure (`algebra/versor.py`)
- propagation (`field/propagate.py`)
- injection / OOV grounding (`ingest/gate.py`)
- vault recall/storage (`vault/store.py`)
- session turn loop (`session/context.py`)
- runtime/eval loops (`chat/runtime.py`, `core/cognition/*`, `evals/*`)
ADRs, session docs, audit artifacts, and handoff briefs stay as Markdown (GitHub-flavored). Plain-text artifacts are diffable, greppable, and readable by every agent in the dispatch pipeline.
Required approach:
Within Markdown, two GitHub-rendered features are sanctioned and otherwise sparingly used:
- Mermaid fenced blocks (` ```mermaid `) when a state machine, sequence, or dependency graph genuinely communicates more than prose. Inline, not in a sidecar file.
- `<details>` / `<summary>` collapsibles to fold long proofs, large tables, or generated logs without losing single-file context.
1. Prefer semantics-preserving cleanup before new knobs.
2. Route hot-path algebra through `algebra.backend` when semantics are identical.
3. Hoist repeated imports and repeated structure-building out of tight loops.
4. Cache only deterministic, immutable, or safely copied structures.
5. Keep exact CGA recall exact; optimize scans with batching/vectorization, not approximation.
6. Prove speed-oriented changes through existing CLI lanes and, when practical, small benchmark/eval evidence.
Out of scope:
- Standalone HTML artifacts with embedded CSS / inline SVG / sidebar navigation.
- Dashboards, status pages, or visualizers as a substitute for a pinned data artifact. If a visualization is load-bearing, the underlying data must live in a deterministic JSON/JSONL/Markdown artifact first.
Never improve speed by:
## Validation lanes
- weakening `versor_condition` thresholds
- skipping closure checks at construction boundaries
- adding hot-path repair/normalization
- replacing exact CGA with cosine/ANN/HNSW
- hiding failures behind retry loops without telemetry
- mutating shared cached state unsafely
For test speed, prefer better validation lanes, small-case eval tests, fixture reuse where safe, and pack/load caching with immutability guarantees. Do not delete meaningful tests just because the full suite is slow.
## Security and Trust-Boundary Doctrine
Every agent must identify user-controlled input and dynamic execution surfaces.
Security hardening should be built into the same PRs that touch those surfaces.
High-risk surfaces:
- `core pack validate` dynamic validator execution
- language/source pack loading
- OOV token grounding and logs
- CLI commands that echo user input
- report/eval output paths
- pack mutation proposals
- any future file/network/database integration
Required approach:
1. Make arbitrary-code execution explicit and opt-in.
2. Reject path traversal and unsafe pack IDs before filesystem access.
3. Centralize display/log handling for user-controlled strings when expanding logging.
4. Keep pack mutation proposal-only unless an explicit reviewed path applies it.
5. Avoid leaking raw sensitive tokens in errors/reports unless the command is explicitly local/debug.
6. Preserve deterministic replay evidence for security-relevant decisions.
Do not add hidden background execution, dynamic imports from untrusted paths, shell passthroughs, or broad filesystem writes without an explicit trust boundary and tests.
## Chat Surface Contract
Do not collapse these fields:
- `surface` — selected user-facing response.
- `walk_surface` — raw manifold/token-walk evidence.
- `articulation_surface` — proposition/realizer surface.
Current policy:
```text
surface = articulation_surface
walk_surface = retained telemetry/evidence
```
If this changes, update `docs/runtime_contracts.md` and contract tests in the
same PR.
## Teaching and Memory Safety
Learning is controlled mutation, not storing everything.
Rules:
- Session memory can be immediate and local.
- Reviewed memory must go through the teaching loop.
- Pack mutation is proposal-only until reviewed.
- User correction must not mutate identity axes, runtime policy, or operator code.
- Identity override attempts must be rejected, not learned.
Use the teaching modules for correction capture/review/store. Do not invent a
parallel correction mechanism inside chat runtime or generation.
## Semantic Pack Rule
Use compact, curated semantic packs. Do not dump broad corpora into runtime.
The core cognition seed pack is meant to provide thought vocabulary, operations,
and relation predicates, not to impersonate large-scale pretraining.
Manifest checksums must be computed from bytes actually written to disk:
```python
checksum = hashlib.sha256(Path(lexicon_path).read_bytes()).hexdigest()
```
Never compute a manifest checksum from a pre-serialization Python string.
## Development Priorities
Current capability sequence:
1. Keep CLI test suites 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 only after replay/eval/calibration remain deterministic.
Do not add dashboards, broad infra, or large test matrices unless they directly
protect or unlock one of the above capabilities.
## Test Discipline
Use the CLI lanes as the standard validation interface:
Use the CLI lanes as the standard validation surface:
```bash
core test --suite smoke -q
@ -288,63 +169,37 @@ core test --suite full -q
core eval cognition
```
For targeted work, run the smallest relevant suite first, then `full` before
merge when practical.
Run the smallest relevant suite first.
Run broader suites before merge when the change touches runtime, algebra, cognition, teaching, packs, or trust boundaries.
Good tests protect:
## Security and trust boundaries
- versor closure
- deterministic replay / trace hash stability
- runtime surface contracts
- exact memory/recall behavior
- identity protection
- reviewed correction safety
- semantic pack loadability and deterministic ordering
- eval/calibration determinism
- hot-path performance semantics
- explicit security trust boundaries
Any change touching user-controlled text, files, dynamic imports, pack loading, validators, logs, or report output must state its trust boundary.
Bad tests preserve private helper shapes, stale constructors, punctuation trivia
outside documented contracts, or legacy behavior that contradicts the current
architecture.
Required defaults:
- explicit opt-in for arbitrary execution
- reject unsafe paths before filesystem access
- centralize safe display/log handling
- no hidden background execution
- no broad filesystem mutation without explicit boundary and tests
## PR Standard
## PR checklist
Every PR must answer:
Before merge, answer:
```text
What cognitive capability, performance property, or security boundary did this add or protect?
What invariant proves it did not corrupt the field?
Which CLI suite/eval proves the relevant lane?
Did it 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?
What capability, performance property, or security boundary did this add or protect?
Which invariant proves the field remained valid?
Which validation lane proves the change?
Did this avoid hidden normalization, stochastic fallback, approximate recall, and unreviewed mutation?
If it touched user input, files, dynamic imports, or logs, what trust boundary was enforced?
```
Prefer small, load-bearing PRs. Do not mix baseline fixes, feature work, and
large reorganization unless the coupling is unavoidable.
## Provider-file policy
## Kernel Substrate / No-New-Legacy Rule
After PR #829, the preferred math comprehension construction path is:
```text
raw problem text → KernelFacts → ProblemFrame → contract-backed derivation organs
```
- Use `generate/problem_frame_builder.py::build_problem_frame` for substrate-backed
fact extraction (scalars, units, hazards, process-frame candidates).
- New derivation capabilities must consume ProblemFrame facts where the substrate can
represent the needed meaning.
- New raw-prose/local-regex parsing inside a derivation organ requires an explicit
`LEGACY_EXCEPTION` comment and migration rationale.
- Guard test: `tests/test_kernel_no_new_legacy_derivation_surfaces.py`.
- Audit map: `docs/analysis/kernel-substrate-deprecation-audit-2026-06-18.md`.
Do not add another isolated benchmark organ with a local prose parser.
## Architecture in One Sentence
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.
`CLAUDE.md`, `GEMINI.md`, and any future provider file must:
- be short
- point here as canonical
- avoid duplicating architecture
- avoid introducing provider-only truth
- differ only where tool startup behavior genuinely requires it

511
CLAUDE.md
View file

@ -1,505 +1,34 @@
# CORE Agent Instructions for Claude
Read this before modifying the repository. CORE is a deterministic cognitive
engine under construction, not a transformer wrapper, not a generic chatbot, and
not an infrastructure playground.
Read this file before modifying the repository.
## End Goal
`AGENTS.md` is the canonical governance file for this repo.
If this file conflicts with `AGENTS.md`, follow `AGENTS.md`.
CORE should become capable of:
## Session start
```text
listen -> comprehend -> recall -> think -> articulate -> learn from reviewed correction -> replay deterministically
```
The working design is now:
```text
CognitiveTurnPipeline
-> intent classification
-> PropositionGraph
-> ArticulationTarget
-> deterministic realizer
-> generation walk telemetry
-> reviewed teaching loop
-> deterministic eval/calibration replay
-> deterministic trace hash
```
The system should become more capable by strengthening this path, not by adding
opaque LLM fallbacks, stochastic sampling, hidden normalization, or broad
infrastructure.
## Philosophical Stance
Truth is coherent. Preserve coherence in algebra, memory, articulation, and
teaching. Identity, truthfulness, and replayability are architectural
commitments, not soft prompt preferences.
Code and tests should make illegal states difficult to represent. Prefer
inspectable state, provenance, and deterministic replay over impressive-looking
but ungrounded outputs.
## Non-Negotiable Field Invariant
Every runtime field state `F` must satisfy:
```text
versor_condition(F) < 1e-6
```
Do not weaken this threshold to make tests pass. Fix the operator/construction
boundary that violated it.
## Normalization Rules
Allowed sites:
- `ingest/gate.py` for raw input injection.
- `language_packs/compiler.py` and vocabulary construction.
- `algebra/versor.py` for algebra-owned sandwich closure.
- `sensorium/*/canonical.py` and pack-governed modality compiler construction
boundaries for pinned signal canonicalization and quantization.
- `session/context.py` for session-scoped **semantic anchoring** of the field
toward the session concept-attractor (the anchor pull, hemisphere
consistency). Allowed ONLY because every such op (1) preserves
`versor_condition` BY CONSTRUCTION — composed from `rotor_power` /
`word_transition_rotor` / `versor_apply` on the Spin manifold, never a
post-hoc `unitize`/grade-projection — AND (2) carries semantic meaning in
the cognitive model. An op that needs a post-hoc closure repair (the
rejected `_slerp_toward`) fails clause (1) and stays forbidden.
Forbidden sites:
- `generate/stream.py`
- `field/propagate.py`
- `vault/store.py`
- logging/telemetry/runtime shell code
Do not add drift repair, grade projection, watchdogs, timers, hot-path
normalizers, or monitoring functions whose only purpose is to repair another
function.
**The bright line — semantic anchoring vs. drift repair.** An op is *semantic
anchoring* (allowed at the sites above) iff it preserves `versor_condition` by
construction AND expresses a relation in the cognitive model. It is *drift
repair* (forbidden) iff its purpose is to restore a numerical invariant a prior
function should have preserved. Closure of field transitions is owned solely
by `algebra/versor.py` (`_close_applied_versor`); no other site may "fix" it.
Naming must not disguise the distinction: an op that anchors semantically must
not be named or documented as a "drift fix".
CGA null vectors are not unit versors. Preserve null vectors as null vectors.
## Core Primitives
Field transition:
```text
versor_apply(V, F) = V * F * reverse(V)
```
Metric/recall:
```text
cga_inner(X, Y)
```
Do not add cosine similarity, HNSW, ANN indexes, or approximate recall to the
runtime path. Vault recall is exact and deterministic.
## Current Key Modules
- `core/cognition/pipeline.py` — cognitive turn spine.
- `core/cognition/result.py` — result object for pipeline evidence.
- `core/cognition/trace.py` — deterministic trace hashing.
- `chat/runtime.py` — user-facing runtime contract.
- `generate/intent.py` — deterministic intent classification.
- `generate/graph_planner.py` — proposition graph and articulation target planning.
- `generate/realizer.py` and `generate/templates.py` — deterministic surface realization.
- `teaching/correction.py`, `teaching/review.py`, `teaching/store.py` — reviewed teaching loop.
- `language_packs/data/en_core_cognition_v1` — core cognition semantic seed pack.
- `evals/*` — deterministic cognition eval harness.
- `calibration/*` — bounded replay-based calibration.
- `docs/runtime_contracts.md` — response, telemetry, memory, identity, and testing contracts.
### Kernel substrate / ProblemFrame (operational path after PR #829)
New derivation capabilities must consume `KernelFacts` / `ProblemFrame` facts where the
substrate can represent the needed meaning (`generate/problem_frame_builder.py`).
```text
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`. Migration map:
`docs/analysis/kernel-substrate-deprecation-audit-2026-06-18.md`.
### GSM8K math comprehension substrate (sealed; serving `7/43/0`, wrong=0 — moves only via ratified PRs)
- `core/reliability_gate/` — calibrated-learning ledger + gate (ADR-0175): `ClassTally` counts, `conservative_floor` (one-sided Wilson, N_MIN=10), θ ceilings.
- `generate/derivation/` — the comprehension composer: `extract.py` (lexeme quantity extraction, EX-1/4/5 + function-word unit filter), `clauses.py` (GB-1 segmentation), `compose.py` (GB-2a list-sum + GB-3a clause-scoped referent guard), `accumulate.py` (GB-3b.1 single-referent gain/loss chaining), `goal_residual.py` (ADR-0207 R4 goal-residual production), `multistep.py`/`search.py` (bounded search), `verify.py` (the wrong=0 self-verification gate: grounding ∧ cue ∧ unit ∧ completeness ∧ uniqueness).
- `generate/cue_precision/` — `(cue, op, unit_shape)` reliability ledger + trainer (ADR-0177 CP-1/CP-2a); inert (consulted by no serving/gate path yet).
- `evals/gsm8k_math/` — `train_sample/` (real GSM8K dev sample, currently 7 correct / 43 refused / 0 wrong), `practice/` (sealed attempt-and-eliminate lane + ADR-0163-F additive set), `confusers/` (ADR-0163-F2 discrimination probe — scored by `wrong→0` + pair-consistency, NOT flip-count).
- `scripts/verify_lane_shas.py`, `scripts/generate_claims.py --check` — the serving-frozen gate (pinned eval-lane SHAs + `CLAIMS.md`).
### Sensorium / modality compiler substrate (parallel, afferent gates; no broad capability claim)
- `sensorium/compiler/` — shared compiler law for content-addressed afferent compilation units, canonical deltas, local arenas, and trace-safe merge hashes.
- `sensorium/audio/` + `sensorium/adapters/audio.py` — `audio_core_v1`, deterministic audio compiler substrate, gate closed by default.
- `sensorium/vision/` + `sensorium/adapters/vision.py` — `vision_core_v1`, tile-first deterministic visual compiler substrate over synthetic eval fixtures, gate closed by default.
- `sensorium/environment/` — ADR-0208 observation-frame contract for bundles of already-compiled afferent units; not late fusion and not a mutable world model.
- `sensorium/sensorimotor/` + `sensorium/adapters/sensorimotor.py` — ADR-0209 afferent proprioception/contact/action-result evidence substrate; no decode path.
- `sensorium/registry.py::decode*` + `AuthorityToken` / `EfferentGate` — ADR-0198 fail-closed efferent governance path. This is not a ratified motor decoder or actuator interface; no real action emission is claimed.
## Efficiency and Performance Doctrine
Performance is part of correctness for this project because slow feedback hides
regressions and encourages unsafe shortcuts. Do not defer obvious hot-path or
validation-lane issues until “later.”
Before changing hot paths, identify whether the change touches:
- algebra backend dispatch
- versor application / closure
- propagation
- injection / OOV grounding
- vault recall/storage
- session turn loop
- runtime/eval loops
Required approach:
1. Prefer semantics-preserving cleanup before new knobs.
2. Use `algebra.backend` for hot-path algebra when semantics are identical.
3. Hoist repeated imports and repeated structure-building out of tight loops.
4. Cache deterministic immutable data only, or return safe copies.
5. Keep exact CGA recall exact; use batching/vectorization, not approximation.
6. Validate speed-oriented changes through CLI lanes and `core eval cognition`.
Never improve speed by weakening closure thresholds, skipping construction
checks, adding hot-path repair, replacing exact CGA with approximate metrics, or
mutating shared cached state unsafely.
For test speed, prefer curated CLI lanes, small-case eval tests, safe fixture
reuse, and immutable pack/load caching. Do not delete meaningful tests just
because the full suite is slow.
## Security and Trust Boundaries
Any change that touches user-controlled text, filesystem paths, dynamic imports,
reports, pack validators, or logs must state the trust boundary.
High-risk surfaces:
- `core pack validate` dynamic validator execution.
- language/source pack loading.
- OOV token grounding and error messages.
- CLI commands that echo user content.
- eval/report output paths.
- pack mutation proposals.
- future file/network/database integrations.
Required approach:
1. Make arbitrary-code execution explicit and opt-in.
2. Reject path traversal and unsafe pack IDs before filesystem access.
3. Centralize safe display/log handling before increasing logging.
4. Keep pack mutation proposal-only unless a reviewed path applies it.
5. Avoid leaking raw sensitive tokens unless the command is explicitly local/debug.
6. Preserve deterministic replay evidence for security-relevant decisions.
Do not add hidden background execution, dynamic imports from untrusted paths,
shell passthroughs, or broad filesystem writes without tests and a documented
trust boundary.
## Runtime Surface Contract
Keep these distinct:
- `surface`: selected user-facing response.
- `walk_surface`: raw manifold/token-walk evidence.
- `articulation_surface`: proposition/realizer surface.
Current policy:
```text
surface = articulation_surface
walk_surface = retained telemetry/evidence
```
Any change must update `docs/runtime_contracts.md` and contract tests in the
same PR.
## Teaching Safety
Learning must be reviewed and auditable.
- Session memory may be immediate.
- Reviewed memory must go through `teaching/*`.
- Pack mutation is proposal-only until reviewed.
- Identity override attempts are rejected.
- User text must not mutate identity axes, runtime policy, or operator code.
Do not create a parallel correction/learning path.
### The learning boundary is typed, not "everything is proposal-only"
A common misreading treats *all* learning as proposal-only. That is a false
bottleneck. The real boundary is between **durable** standing and
**provisional** standing, and it is already mechanically enforced — the rule
below names what each invariant guarantees, it does not loosen any of them.
- **Durable mutation stays reviewed or proof-carrying.** Corpus / pack /
policy / identity changes, and any promotion to COHERENT/verified standing,
go through the reviewed teaching loop (`teaching/*`, proposal-only) or the
proof-carrying promotion gate (ADR-0218 `apply_certified_promotion`, which
re-verifies the entailment from a curator-certified coherent base before the
flip).
- **Provisional state may update autonomously — iff typed, isolated,
replayable, and unable to masquerade as ratified truth.** This covers
session memory, sealed practice ledgers, SPECULATIVE idle consolidation of
soundly-derived facts, reliability-ledger counts, proposal emission, and
disclosed licensed estimates. Each is written SPECULATIVE (never COHERENT),
through the same `VaultStore.store` path (no parallel memory), deterministically
(no clock, no LLM, no sampling), and carries its standing honestly
(`basis="as_told"`, `[approximate]`, "proposal", …).
This boundary is a set of failing-when-violated invariants, not a convention:
- **INV-21** — only allowlisted modules may call `VaultStore.store(...)`.
- **INV-22 / INV-23** — an unmarked pack row and an unmarked `store()` default
to SPECULATIVE; COHERENT requires an explicit stamp.
- **INV-24** — every `vault.recall` callsite is categorized; user-facing
evidence must pass `min_status=COHERENT`.
- **INV-29** — only `vault/store.py` may transition an `epistemic_status`; the
only *default-reachable* COHERENT producer is the certificate-gated
`apply_certified_promotion`. (Honest wrinkle: ADR-0148
`promote_eligible_entries` is a second, non-certificate COHERENT path, but it
is opt-in — it fires only when a caller passes a promotion policy — and is
off by default.)
- **INV-30** — the open-world `determine()` gear constructs only
`Determined(answer=True)` or refuses; it can never assert `answer=False`.
Closed-world entailed-negation (assert-False) must use a distinct
closed-world type and entry point, never the open-world path.
When you add an autonomous learning surface, it must land inside this boundary
(SPECULATIVE, same store path, replayable) and the relevant invariant above must
*fail loudly* if it does not. An autonomous path that can reach COHERENT, emit
verified without a replayed certificate, persist non-replayably, or assert a
closed-world False into the open-world runtime is a boundary breach, not a
feature.
## Semantic Pack Discipline
Prefer compact, curated packs. Do not bulk-ingest corpora into runtime.
`en_core_cognition_v1` supplies thought vocabulary, operations, and relation
predicates. Extend it cautiously, with deterministic ordering and pack tests.
Manifest checksums must hash the bytes actually written to disk:
```python
checksum = hashlib.sha256(Path(lexicon_path).read_bytes()).hexdigest()
```
## Documentation Discipline
ADRs, session docs, audit artifacts, and handoff briefs stay as Markdown
(GitHub-flavored). Plain-text artifacts are diffable, greppable, and
readable by every agent in the dispatch pipeline.
Within Markdown, two GitHub-rendered features are sanctioned and otherwise
sparingly used:
- Mermaid fenced blocks (` ```mermaid `) when a state machine, sequence,
or dependency graph genuinely communicates more than prose. Inline,
not in a sidecar file.
- `<details>` / `<summary>` collapsibles to fold long proofs, large
tables, or generated logs without losing single-file context.
Out of scope:
- Standalone HTML artifacts with embedded CSS / inline SVG / sidebar
navigation. The "open in browser" model breaks `git diff`, breaks
determinism (CSS regen ordering, SVG element ordering), and breaks
cross-agent legibility.
- Dashboards, status pages, or visualizers as a substitute for a
pinned data artifact. If a visualization is load-bearing, the
underlying data must live in a deterministic JSON/JSONL/Markdown
artifact first; any rendering is a read-only view of that artifact.
Diagrams go inside the doc that needs them. Specs do not become
single-file applications.
## Schema-Defined Proof Obligations
When a schema, type, or struct exists for the sole purpose of naming a
structural property the architecture claims to hold
(``HolonomyAlignmentCase``, ``RoundTripFilter``, the various ``Result``
discriminants), the obligation is real only when an executing test can
**meaningfully fail** under the violations it is written to catch.
A test that passes under conditions that bypass the obligation it
nominally proves is decoration, not proof. Before treating a schema
type as a verified property:
1. Identify the violations the schema is written to catch.
2. Confirm an existing test would fail if exactly one of those
violations were silently introduced (e.g. by mutating a weight,
skipping a step, swapping a fallback).
3. If no such test exists, the obligation is asserted but not proven —
record the gap in a follow-up doc rather than treating the schema
as load-bearing.
This rule generalises the wrong=0 invariant. ``wrong == 0`` holds
because the admissibility gate, the round-trip filter, and the
multi-branch disagreement check are all wired to fail loudly when
violated. The same discipline applies to every other "this design
guarantees X" claim in the codebase.
## Validation Through CLI
Use CLI lanes instead of ad hoc pytest fragments:
1. Read `AGENTS.md`.
2. Read `docs/runtime_contracts.md`.
3. Read the most recent `HANDOFF-*.md` from the last 3 days if one exists and is relevant.
4. Confirm repository root and inspect the working tree before editing.
5. Run:
```bash
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 when practical.
6. State the task scope before making changes:
- which module(s) you will touch
- which invariant or contract you must preserve
## Work Sequencing
## Working rules
Current near-term sequence:
- Do not invent alternate architecture, alternate invariants, or alternate memory rules.
- Use the smallest relevant validation lane first, then broader lanes as required by change scope.
- For docs/config-only changes, smoke is usually sufficient unless the change affects executable paths, tests, CLI behavior, or generated artifacts.
- Prefer small, load-bearing changes.
- Use `AGENTS.md` as the source of truth for architecture, invariants, validation, and PR standards.
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.
## Session end
Avoid broad docs-first churn, dashboard work, or large infrastructure unless it
unlocks one of these steps.
The afferent sensorium/modalities arc (ADR-0013 -> 0181/0197/0208/0209; ADR-0198
reserves the efferent/motor half) is a **sanctioned parallel track** — not part
of the near-term sequence above and not licensed to displace it. It is disjoint
from the GSM8K serving path (no `generate.derivation` / `core.reliability_gate`
import), so it cannot regress the serving metric; its efferent half stays gated
behind ADR-0198's fail-closed boundary and a dedicated motor governance ADR
(ratified afferent ADRs carry `Accepted (ratified ...)`; ADR-0198 stays a
partially-implemented spike).
## Lookback Review Discipline
Multi-PR architectural work accumulates latent defects when each PR
is reviewed only against its own acceptance criteria. A hazard
introduced in PR N can sit dormant until PR N+2 exercises it — by
which point the substrate is harder to fix and three PRs are
implicated rather than one.
**Mandatory lookback review** is triggered at three points:
1. **Before starting the next phase of a multi-phase ADR.** Before
any code on Phase N+1, audit Phase N's shipped substrate. Check
for: ADR-doc vs implementation drift, untested predicate paths,
wrong=0 hazard surfaces, cross-phase trace/event/rank consistency,
things the ADR says that didn't actually ship.
2. **Before merging a stacked PR sequence into main.** When 2+ PRs
stack (PR #420 stacked on #416, PR #423 stacked on #420), the
review-each-PR-individually pattern misses cross-PR consistency
issues. Audit the whole stack as one unit before any merge.
3. **After any 3+ PR sequence on the same module or architectural
surface.** When work concentrates on one area, regression risk
compounds. Audit before claiming the surface is "stable" or
"ready for the next layer."
**What a lookback review covers** (template — adjust per scope):
- **Documentation drift.** Does what shipped match what the ADR / brief
said would ship? Signature differences, scope reductions, missing
pieces — flag them.
- **Test coverage gaps.** Run the test suite under coverage. For every
predicate/branch in a closed-set contract (like
`VALID_PREDICATE_NAMES`), confirm at least one test asserts the
specific elimination/admission path. Vacuous tests (assertions
that pass under broken impl) are coverage gaps.
- **Parity gaps.** When a new implementation claims byte-equivalence
with an existing one, exercise BOTH on the same inputs and confirm
identical outputs — including failure modes, not just success.
- **wrong=0 hazard surface.** Every new code path: under what input
conditions could it admit a candidate the prior path would have
refused? Trace upstream to confirm no input class can trigger it.
If a class CAN trigger it, build the defensive refusal NOW, before
the next phase makes it load-bearing.
- **Cross-PR consistency.** Trace event shapes, rank handling,
determinism contracts, dataclass invariants — do they compose
cleanly across PRs?
- **Honest LOC accounting.** Did this phase net add or net remove
lines? ADR claims of "removes ~N lines" only count post-collapse;
intermediate phases that ADD substrate before removal happens
should be called out.
**Output.** The review produces a structured report with findings
categorized as: solid, gaps (no risk), drift (need amendment), and
hazards (live wrong=0 risks). Hazards require a fix-before-next-phase
decision.
**Cost.** A lookback review on a 3-PR substrate typically takes
20-40 minutes of focused tool calls. Skipping it costs more: every
PR built on an undetected hazard becomes implicated when the hazard
fires, and the fix has to land across multiple PRs instead of one.
## Architectural Scan Exclusions
The invariant tests in `tests/test_architectural_invariants.py` perform
full source-tree walks to enforce structural claims (INV-02, INV-21,
INV-24). These scans **must** exclude `.claude/` from traversal.
**Why this matters:** Agent operators (Claude Code, Codex, Gemini) create
worktrees under `.claude/worktrees/`. Those worktrees contain full copies
of the source tree — including `vault/`, `chat/`, `generate/`, etc. — and
will trip every structural invariant that scans for forbidden callsites.
The failures are silent killers: the tests report real-looking violations
against files that aren't in the live codebase, poisoning the smoke suite
and masking actual regressions.
**Maintained exclusion sets** (keep `.claude` in both):
```python
# INV-02 os.walk exclusion (test_normalize_not_called_outside_gate)
{".git", ".venv", "__pycache__", ".pytest_cache", ".hypothesis", ".claude"}
# INV-21 / INV-24 rglob exclusion (EXCLUDED_DIRS)
{"tests", "evals", "benchmarks", "scripts", "docs",
"core-rs", ".venv", "__pycache__", ".claude"}
```
If you add a new source-tree scan to the invariant suite, add `.claude`
to its exclusion set before the first commit. Never rely on worktrees
being pruned — they can persist across sessions and CI runs.
## PR Checklist
Before opening or merging, answer:
```text
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?
```
Prefer small, load-bearing PRs with clear evidence.
When a session produced meaningful implementation or architectural analysis, write or update a handoff document using the repo’s handoff template and current naming convention.

34
GEMINI.md Normal file
View file

@ -0,0 +1,34 @@
# CORE Agent Instructions for Gemini
Read this file before modifying the repository.
`AGENTS.md` is the canonical governance file for this repo.
If this file conflicts with `AGENTS.md`, follow `AGENTS.md`.
## Session start
1. Read `AGENTS.md`.
2. Read `docs/runtime_contracts.md`.
3. Read the most recent `HANDOFF-*.md` from the last 3 days if one exists and is relevant.
4. Confirm repository root and inspect the working tree before editing.
5. Run:
```bash
core test --suite smoke -q
```
6. State the task scope before making changes:
- which module(s) you will touch
- which invariant or contract you must preserve
## Working rules
- Do not invent alternate architecture, alternate invariants, or alternate memory rules.
- Use the smallest relevant validation lane first, then broader lanes as required by change scope.
- For docs/config-only changes, smoke is usually sufficient unless the change affects executable paths, tests, CLI behavior, or generated artifacts.
- Prefer small, load-bearing changes.
- Use `AGENTS.md` as the source of truth for architecture, invariants, validation, and PR standards.
## Session end
When a session produced meaningful implementation or architectural analysis, write or update a handoff document using the repo’s handoff template and current naming convention.

138
GPT55.md
View file

@ -1,138 +0,0 @@
# CORE Agent Instructions for GPT-5.5 (o3-class)
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.
> **You are stateless across API sessions.** You have no persistent memory
> of prior conversations. Complete the
> [Session Start Checklist](#session-start-checklist) before any edits.
---
## Session Start Checklist
1. **Read this file in full.**
2. **Read `AGENTS.md` in full.**
3. **Read `docs/runtime_contracts.md` in full.**
4. **Run the startup guard** — enforces fresh-base and clean-tree invariants:
```bash
source scripts/agent_startup.sh
```
For a PR-resume task: `CODEX_ALLOW_NON_MAIN_BASE=1 source scripts/agent_startup.sh`
5. **Run the smoke suite:**
```bash
core test --suite smoke -q
```
6. **Check for a handoff doc** — read the most recent `HANDOFF-*.md` if one
exists dated within the last 3 days.
7. **State your task scope** — before editing, name the module(s) and the
invariant you will prove was not violated.
---
## Reasoning and Tool Use
GPT-5.5 (o3-level) has strong multi-step reasoning. Use it here by:
- **Reasoning through the full operator chain** before proposing edits to
algebra or field modules. Do not shortcut the math.
- **Using tool calls** to sweep import graphs and call sites before editing.
- **Stating your reasoning** about why an edit preserves versor_condition
before writing the code.
For extended thinking mode: enable it for any task touching `algebra/`,
`field/`, `vault/`, `calibration/`, or `core/cognition/`.
---
## NON-NEGOTIABLE INVARIANTS
```
❌ versor_condition(F) < 1e-6 at every runtime field state.
Fix the operator/construction boundary; do not weaken the threshold.
❌ Normalization only at:
ingest/gate.py
language_packs/compiler.py
algebra/versor.py
sensorium/*/canonical.py
session/context.py (semantic anchoring only — see CLAUDE.md)
Forbidden in: generate/stream.py, field/propagate.py, vault/store.py,
logging/telemetry layers.
❌ No cosine similarity, HNSW, ANN, or approximate recall in runtime.
Vault recall is exact and deterministic.
❌ No stochastic generation or opaque LLM fallbacks in the cognitive path.
❌ No pack mutation outside the proposal-only reviewed teaching loop.
❌ INV-21/22/23/24/29/30 (see CLAUDE.md for full text).
```
---
## GPT-5.5 Specific Cautions
GPT-5.5's code generation is fluent and fast. That fluency creates
specific risks for CORE:
- **Do not generate "helpful" utility wrappers** that centralize normalization
or add intermediate caching layers. CORE's architecture is already
explicit about where these belong.
- **Do not add type coercions** in hot-path algebra that silently
re-normalize field state.
- **Do not suggest async/concurrent refactors** to vault or algebra paths
without a full trace of the determinism contract.
- **Tool-use completions that look finished may not be** — always run the
CLI validation suite, do not assume correctness from code inspection alone.
---
## Pre-Edit Sweep Protocol
Before editing any module in `algebra/`, `field/`, `generate/`, `vault/`,
`core/cognition/`, `teaching/`, or `calibration/`:
1. Trace every import of the target module.
2. Identify all callers of the target function/class.
3. Check `evals/` and `calibration/` for tests covering the changed path.
4. Only then propose edits.
---
## End-of-Session Handoff Requirement
At the end of every session, write a handoff document using the template
at `docs/handoff_template.md`. Name it:
```
HANDOFF-gpt55-YYYY-MM-DD.md
```
---
## 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.
See `AGENTS.md` for the full cognitive path, key modules, and PR checklist.
---
## CLI Validation Lanes
```bash
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
```

382
GROK.md
View file

@ -1,382 +0,0 @@
# 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](#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](#workspace-hygiene--branchworktree-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:**
```bash
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:
```bash
pwd
git rev-parse --show-toplevel
test -f GROK.md
test -f AGENTS.md
```
If the current directory is not the repository root, run:
```bash
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:
```bash
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:
```bash
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:
```bash
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
**Run the startup guard first** — it automates steps 2–4 and will hard-stop if the worktree is stale:
```bash
source scripts/agent_startup.sh
```
For a new task (default, no env vars) the script requires `HEAD == origin/main` and a clean tree.
For a PR-resume task, set `CODEX_ALLOW_NON_MAIN_BASE=1`; the script then verifies `origin/main` is a strict ancestor of `HEAD`.
If you cannot source the script, perform the equivalent steps manually:
```bash
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`:
```bash
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:
```text
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:
```bash
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`).
```text
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.
```text
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:
```text
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
```bash
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.