From 63464144c53f2499b1ea9e5bf3799e80c57a0b53 Mon Sep 17 00:00:00 2001 From: Shay Date: Tue, 30 Jun 2026 10:54:53 -0700 Subject: [PATCH] docs: consolidate agent architectural governance into AGENTS.md 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. --- AGENTS.md | 409 ++++++++++++++----------------------------- CLAUDE.md | 511 +++--------------------------------------------------- GEMINI.md | 34 ++++ GPT55.md | 138 --------------- GROK.md | 382 ---------------------------------------- 5 files changed, 186 insertions(+), 1288 deletions(-) create mode 100644 GEMINI.md delete mode 100644 GPT55.md delete mode 100644 GROK.md diff --git a/AGENTS.md b/AGENTS.md index e5fa9d8a..09bc6d27 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. +- `
` / `` 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 diff --git a/CLAUDE.md b/CLAUDE.md index bf2ac299..dfa8e330 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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. -- `
` / `` 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. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 00000000..e8fbd251 --- /dev/null +++ b/GEMINI.md @@ -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. diff --git a/GPT55.md b/GPT55.md deleted file mode 100644 index 86b9926f..00000000 --- a/GPT55.md +++ /dev/null @@ -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 -``` diff --git a/GROK.md b/GROK.md deleted file mode 100644 index 2046535d..00000000 --- a/GROK.md +++ /dev/null @@ -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 -- -git log --oneline --decorate --all -- -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 : " -- -``` - -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- origin/main -b -cd ../core- -``` - -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/- -fix/- -chore/- -``` - -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.