From 33aed4e550c91bda84d5e59040bdaf8555c28cb0 Mon Sep 17 00:00:00 2001 From: Shay Date: Fri, 15 May 2026 06:36:07 -0700 Subject: [PATCH] Update agent guidance for current CORE roadmap - update AGENTS.md with current cognitive architecture and operating doctrine - align CLAUDE.md with current CORE roadmap and invariants - add GitHub Copilot/Codex instructions for agentic coding tools - document CLI validation lanes, teaching safety, semantic pack discipline, and PR standards --- .github/copilot-instructions.md | 110 ++++++++++++++ AGENTS.md | 256 ++++++++++++++++++++++++++------ CLAUDE.md | 195 +++++++++++++++++++++--- 3 files changed, 496 insertions(+), 65 deletions(-) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..94663794 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,110 @@ +# CORE Agentic Coding Instructions + +Use these instructions for Copilot/Codex-style repository work. + +## Mission + +CORE is a deterministic cognitive engine. The near-term goal is basic +teachable cognitive chat: + +```text +listen -> comprehend -> recall -> think -> articulate -> learn from reviewed correction -> replay deterministically +``` + +Do not treat the repository as a normal chatbot wrapper or transformer project. +Do not add hidden LLM fallbacks, stochastic generation, or broad infrastructure +that bypasses the geometric cognitive path. + +## Current Architecture + +The cognitive path is centered on: + +- `core/cognition/pipeline.py` +- `generate/intent.py` +- `generate/graph_planner.py` +- `generate/realizer.py` +- `teaching/correction.py`, `teaching/review.py`, `teaching/store.py` +- `language_packs/data/en_core_cognition_v1` + +The runtime response contract is documented in `docs/runtime_contracts.md`. +Follow it. + +## Hard Invariants + +Runtime field states must satisfy: + +```text +versor_condition(F) < 1e-6 +``` + +Allowed construction/closure sites: + +- `ingest/gate.py` +- `language_packs/compiler.py` / vocabulary construction +- `algebra/versor.py` + +Forbidden hot-path repair sites: + +- `generate/stream.py` +- `field/propagate.py` +- `vault/store.py` +- telemetry/logging shell code + +Do not add grade monitors, drift timers, watchdog repair functions, ANN/HNSW, +cosine similarity, or approximate recall. + +## Surface Contract + +Keep these separate: + +- `surface`: selected user-facing response. +- `walk_surface`: raw generation/manifold evidence. +- `articulation_surface`: proposition/realizer surface. + +Current policy: + +```text +surface = articulation_surface +walk_surface = retained telemetry/evidence +``` + +## Teaching Safety + +Learning is reviewed mutation: + +- Session memory can be immediate. +- Reviewed memory must use `teaching/*`. +- Pack mutation is proposal-only until reviewed. +- Identity override attempts are rejected. +- User text cannot mutate identity axes, runtime policy, or operator code. + +## Validation + +Use CLI suites: + +```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 +``` + +For a feature PR, run the smallest relevant suite and then `full` when +practical. + +## PR Standard + +Every change should state: + +```text +Capability added/protected: +Invariant protected: +CLI suite run: +No hidden normalization / stochastic fallback / unreviewed mutation: +``` + +Prefer small PRs. Do not combine baseline repair, feature work, and broad +reorganization unless unavoidable. diff --git a/AGENTS.md b/AGENTS.md index 2a0c177e..deabe9a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,65 +1,233 @@ -# CORE-AI Agent Instructions +# CORE Agent Instructions -## The Invariant (Read Before Touching Any Code) +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. -Every field state F must satisfy: +## North Star - ||F * reverse(F) - 1||_F < 1e-6 +CORE should become capable of: -This is checked by algebra/versor.py::versor_condition(). +```text +listen -> comprehend -> recall -> think -> articulate -> learn from reviewed correction -> replay deterministically +``` -## What You Must Never Add +The current path is intentionally staged: -- Any normalization call outside ingest/gate.py -- Grade guards, grade monitors, or grade projection in the hot path -- Drift correction, correction thresholds, or correction timers -- ANN indexes, HNSW, cosine similarity, or approximate distance -- Field energy measurement or pseudoscalar accumulation checks -- Any function whose only job is to watch or repair another function +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. -If you think you need one of these, you have an unclosed operation upstream. -Find it and close it. +Do not skip ahead by adding opaque models, stochastic generation, or broad +infrastructure that hides whether CORE itself is improving. -## The Two Allowed Primitives +## Philosophical and Architectural Stance -Field transition: algebra/versor.py::versor_apply(V, F) -> V*F*reverse(V) -Distance metric: algebra/cga.py::cga_inner(X, Y) -> -d^2 / 2 +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. -These are the only primitives. Everything else is built from them. +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. -## Language Pack Checksum Rule (Critical) +## The Hard Field Invariant -Manifest checksums MUST be computed by reading back the bytes actually -written to disk — never from an in-memory string before serialization: +Every runtime field state `F` must satisfy: - # CORRECT — hash what disk holds - checksum = hashlib.sha256(Path(lexicon_path).read_bytes()).hexdigest() +```text +versor_condition(F) < 1e-6 +``` - # WRONG — Python str != unicode-escaped JSON bytes on disk - checksum = hashlib.sha256(content_str.encode('utf-8')).hexdigest() +This is checked by `algebra/versor.py::versor_condition()`. -The GitHub API (and git) store JSON with unicode escapes (\u05d3, not ד). -Python json.dumps() with ensure_ascii=False produces different bytes. -Always write the file first, then read_bytes() to get the checksum. +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. -## Implementation Order +## Normalization and Closure Rules -Do not skip steps. Run the invariant test after each step before writing the next. +Allowed closure/construction boundaries: -1. algebra/cl41.py -2. algebra/versor.py -> tests/test_versor_closure.py must pass -3. algebra/cga.py -> tests/test_null_cone.py must pass -4. algebra/holonomy.py -> tests/test_holonomy.py must pass -5. ingest/gate.py -6. vocab/manifold.py -7. field/state.py + field/propagate.py -8. vault/store.py -> tests/test_vault_recall.py must pass -9. persona/motor.py -> tests/test_motor.py must pass -10. generate/stream.py -11. session/context.py -12. language_packs/compiler.py -> tests/test_holonomy_resonance.py must pass +- `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: + +- `generate/stream.py` +- `field/propagate.py` +- `vault/store.py` +- runtime telemetry/logging layers + +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. + +CGA null vectors are geometric points and must remain null. Do not force null +vectors into unit-versor closure. + +## The Two Core Primitives + +Field transition: + +```text +algebra/versor.py::versor_apply(V, F) -> V * F * reverse(V) +``` + +Distance/recall metric: + +```text +algebra/cga.py::cga_inner(X, Y) +``` + +Do not add ANN, HNSW, cosine similarity, approximate nearest-neighbor recall, +or non-CGA ranking to runtime memory. Vault recall is exact and deterministic. + +## Current Runtime/Cognition Shape + +The live cognitive path is now: + +```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 +``` + +Important 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 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. +- `docs/runtime_contracts.md` — runtime response, memory, identity, and testing contracts. + +## 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 green. +2. Integrate semantic seed surfaces into realizer/cognition quality. +3. Add cognitive eval harness. +4. Add operator calibration from deterministic replay evidence. +5. Expand curriculum teaching only after the loop remains 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: + +```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 +``` + +For targeted work, run the smallest relevant suite first, then `full` before +merge when practical. + +Good tests protect: + +- 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 + +Bad tests preserve private helper shapes, stale constructors, punctuation trivia +outside documented contracts, or legacy behavior that contradicts the current +architecture. + +## PR Standard + +Every PR must answer: + +```text +What cognitive capability did this add or protect? +What invariant proves it did not corrupt the field? +Which CLI suite proves the relevant lane? +Did it avoid hidden normalization, stochastic fallback, and unreviewed mutation? +``` + +Prefer small, load-bearing PRs. Do not mix baseline fixes, feature work, and +large reorganization unless the coupling is unavoidable. ## Architecture in One Sentence -Raw input -> inject once -> versor on the manifold -> versor_apply every step -> -CGA inner product for recall and decoding -> persona motor for voicing -> done. +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, and replayable trace. diff --git a/CLAUDE.md b/CLAUDE.md index 307e24ac..79428ff7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,33 +1,186 @@ -# CORE-AI Agent Instructions +# CORE Agent Instructions for Claude -## The Invariant (Read Before Touching Any Code) +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. -Every field state F must satisfy: +## End Goal - ||F * reverse(F) - 1||_F < 1e-6 +CORE should become capable of: -This is checked by algebra/versor.py::versor_condition(). +```text +listen -> comprehend -> recall -> think -> articulate -> learn from reviewed correction -> replay deterministically +``` -## What You Must Never Add +The working design is now: -- Any normalization call outside ingest/gate.py -- Grade guards, grade monitors, or grade projection in the hot path -- Drift correction, correction thresholds, or correction timers -- ANN indexes, HNSW, cosine similarity, or approximate distance -- Field energy measurement or pseudoscalar accumulation checks -- Any function whose only job is to watch or repair another function +```text +CognitiveTurnPipeline + -> intent classification + -> PropositionGraph + -> ArticulationTarget + -> deterministic realizer + -> generation walk telemetry + -> reviewed teaching loop + -> deterministic trace hash +``` -If you think you need one of these, you have an unclosed operation upstream. -Find it and close it. +The system should become more capable by strengthening this path, not by adding +opaque LLM fallbacks, stochastic sampling, hidden normalization, or broad +infrastructure. -## The Two Allowed Primitives +## Philosophical Stance -Field transition: algebra/versor.py::versor_apply(V, F) -> V*F*reverse(V) -Distance metric: algebra/cga.py::cga_inner(X, Y) -> -d^2 / 2 +Truth is coherent. Preserve coherence in algebra, memory, articulation, and +teaching. Identity, truthfulness, and replayability are architectural +commitments, not soft prompt preferences. -These are the only primitives. Everything else is built from them. +Code and tests should make illegal states difficult to represent. Prefer +inspectable state, provenance, and deterministic replay over impressive-looking +but ungrounded outputs. -## Architecture in One Sentence +## Non-Negotiable Field Invariant -Raw input -> inject once -> versor on the manifold -> versor_apply every step -> -CGA inner product for recall and decoding -> persona motor for voicing -> done. +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. + +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. + +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. +- `docs/runtime_contracts.md` — response, telemetry, memory, identity, and testing contracts. + +## 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. + +## 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() +``` + +## Validation Through CLI + +Use CLI lanes instead of ad hoc pytest fragments: + +```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 +``` + +Run the smallest relevant suite first, then `full` before merge when practical. + +## Work Sequencing + +Current near-term sequence: + +1. Keep CLI lanes green. +2. Integrate semantic seed relations into realizer/cognition quality. +3. Add cognitive eval harness. +4. Add deterministic operator calibration from replay evidence. +5. Expand curriculum teaching after the loop is stable. + +Avoid broad docs-first churn, dashboard work, or large infrastructure unless it +unlocks one of these steps. + +## PR Checklist + +Before opening or merging, answer: + +```text +What capability did this add or protect? +Which invariant proves the field remains valid? +Which CLI suite proves the lane? +Did this avoid hidden normalization, stochastic fallback, and unreviewed mutation? +``` + +Prefer small, load-bearing PRs with clear evidence.