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
This commit is contained in:
Shay
GitHub
parent
b4ecf67e35
commit
33aed4e550
3 changed files with 496 additions and 65 deletions
110
.github/copilot-instructions.md
vendored
Normal file
110
.github/copilot-instructions.md
vendored
Normal file
|
|
@ -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.
|
||||||
256
AGENTS.md
256
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
|
1. Maintain algebra/runtime invariants.
|
||||||
- Grade guards, grade monitors, or grade projection in the hot path
|
2. Use `CognitiveTurnPipeline` as the spine.
|
||||||
- Drift correction, correction thresholds, or correction timers
|
3. Classify intent and build proposition graphs.
|
||||||
- ANN indexes, HNSW, cosine similarity, or approximate distance
|
4. Plan articulation targets and realize them deterministically.
|
||||||
- Field energy measurement or pseudoscalar accumulation checks
|
5. Capture reviewed teaching corrections safely.
|
||||||
- Any function whose only job is to watch or repair another function
|
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.
|
Do not skip ahead by adding opaque models, stochastic generation, or broad
|
||||||
Find it and close it.
|
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)
|
Truth is coherent. CORE's work is to preserve coherent structure from input to
|
||||||
Distance metric: algebra/cga.py::cga_inner(X, Y) -> -d^2 / 2
|
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
|
Every runtime field state `F` must satisfy:
|
||||||
written to disk — never from an in-memory string before serialization:
|
|
||||||
|
|
||||||
# CORRECT — hash what disk holds
|
```text
|
||||||
checksum = hashlib.sha256(Path(lexicon_path).read_bytes()).hexdigest()
|
versor_condition(F) < 1e-6
|
||||||
|
```
|
||||||
|
|
||||||
# WRONG — Python str != unicode-escaped JSON bytes on disk
|
This is checked by `algebra/versor.py::versor_condition()`.
|
||||||
checksum = hashlib.sha256(content_str.encode('utf-8')).hexdigest()
|
|
||||||
|
|
||||||
The GitHub API (and git) store JSON with unicode escapes (\u05d3, not ד).
|
If a propagation path violates this invariant, fix the operator path or the
|
||||||
Python json.dumps() with ensure_ascii=False produces different bytes.
|
explicit algebra/construction boundary that owns the transition. Do not hide
|
||||||
Always write the file first, then read_bytes() to get the checksum.
|
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
|
- `ingest/gate.py` for raw prompt injection.
|
||||||
2. algebra/versor.py -> tests/test_versor_closure.py must pass
|
- `language_packs/compiler.py` / vocabulary construction.
|
||||||
3. algebra/cga.py -> tests/test_null_cone.py must pass
|
- `algebra/versor.py` where algebraic sandwich output closure belongs.
|
||||||
4. algebra/holonomy.py -> tests/test_holonomy.py must pass
|
|
||||||
5. ingest/gate.py
|
Forbidden hot-path repair sites:
|
||||||
6. vocab/manifold.py
|
|
||||||
7. field/state.py + field/propagate.py
|
- `generate/stream.py`
|
||||||
8. vault/store.py -> tests/test_vault_recall.py must pass
|
- `field/propagate.py`
|
||||||
9. persona/motor.py -> tests/test_motor.py must pass
|
- `vault/store.py`
|
||||||
10. generate/stream.py
|
- runtime telemetry/logging layers
|
||||||
11. session/context.py
|
|
||||||
12. language_packs/compiler.py -> tests/test_holonomy_resonance.py must pass
|
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
|
## Architecture in One Sentence
|
||||||
|
|
||||||
Raw input -> inject once -> versor on the manifold -> versor_apply every step ->
|
Raw input becomes a closed versor field once; thought evolves through exact
|
||||||
CGA inner product for recall and decoding -> persona motor for voicing -> done.
|
versor transitions and CGA recall; cognition is structured as intent,
|
||||||
|
proposition graph, articulation target, deterministic realization, reviewed
|
||||||
|
memory, and replayable trace.
|
||||||
|
|
|
||||||
195
CLAUDE.md
195
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
|
```text
|
||||||
- Grade guards, grade monitors, or grade projection in the hot path
|
CognitiveTurnPipeline
|
||||||
- Drift correction, correction thresholds, or correction timers
|
-> intent classification
|
||||||
- ANN indexes, HNSW, cosine similarity, or approximate distance
|
-> PropositionGraph
|
||||||
- Field energy measurement or pseudoscalar accumulation checks
|
-> ArticulationTarget
|
||||||
- Any function whose only job is to watch or repair another function
|
-> 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.
|
The system should become more capable by strengthening this path, not by adding
|
||||||
Find it and close it.
|
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)
|
Truth is coherent. Preserve coherence in algebra, memory, articulation, and
|
||||||
Distance metric: algebra/cga.py::cga_inner(X, Y) -> -d^2 / 2
|
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 ->
|
Every runtime field state `F` must satisfy:
|
||||||
CGA inner product for recall and decoding -> persona motor for voicing -> done.
|
|
||||||
|
```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.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue