feat: add Grok 4.3 agent config, GROK.md, GPT55.md, handoff template, and .env additions
- GROK.md: full agent instructions optimized for Grok 4.3 high-effort mode - GPT55.md: agent instructions for GPT-5.5 (o3-level reasoning, stateless) - docs/handoff_template.md: mandatory cross-session handoff artifact template - .env.grok43: Grok 4.3 environment config additions (do not commit secrets) - AGENTS.md: prepend Grok 4.3 multi-agent/Arena mode addendum block
This commit is contained in:
Shay
parent
5f6e9f5e08
commit
9b058bc3cd
4 changed files with 483 additions and 0 deletions
25
.env.grok43
Normal file
25
.env.grok43
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
# Grok 4.3 environment configuration for CORE
|
||||
# -----------------------------------------------
|
||||
# Copy relevant variables into your .env (which is gitignored).
|
||||
# Do NOT commit actual API keys — this file is for reference only.
|
||||
#
|
||||
# Required for Grok 4.3 via xAI API or Grok Build CLI:
|
||||
|
||||
# Model selection
|
||||
GROK_MODEL=grok-4.3
|
||||
|
||||
# Always use high effort for algebra/field/cognition work.
|
||||
# Acceptable values: high | medium | low
|
||||
# Default in xAI API is low — override it here.
|
||||
GROK_REASONING_EFFORT=high
|
||||
|
||||
# Context budget — leave ~200k headroom under the 1M cap for tool outputs
|
||||
# and intermediate reasoning.
|
||||
GROK_CONTEXT_BUDGET=800000
|
||||
|
||||
# API key — fill in your actual key in .env, never here
|
||||
# XAI_API_KEY=xai-...
|
||||
|
||||
# Optional: Grok Build CLI config
|
||||
# GROK_BUILD_ARENA_MODE=true # enable parallel subagent mode
|
||||
# GROK_BUILD_MAX_AGENTS=4 # limit parallelism to 4 subagents
|
||||
133
GPT55.md
Normal file
133
GPT55.md
Normal file
|
|
@ -0,0 +1,133 @@
|
|||
# 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 smoke suite:**
|
||||
```bash
|
||||
core test --suite smoke -q
|
||||
```
|
||||
5. **Check for a handoff doc** — read the most recent `HANDOFF-*.md` if one
|
||||
exists dated within the last 3 days.
|
||||
6. **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
|
||||
```
|
||||
233
GROK.md
Normal file
233
GROK.md
Normal file
|
|
@ -0,0 +1,233 @@
|
|||
# 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.
|
||||
|
||||
---
|
||||
|
||||
## 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. **Run the smoke suite and report pass/fail:**
|
||||
```bash
|
||||
core test --suite smoke -q
|
||||
```
|
||||
5. **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.
|
||||
6. **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–5. History
|
||||
does not survive context resets. Ground yourself in the repo.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
---
|
||||
|
||||
## NON-NEGOTIABLE INVARIANTS
|
||||
|
||||
These are not guidelines. Violating any one of them is a bug that must be
|
||||
reverted before merge.
|
||||
|
||||
```
|
||||
❌ versor_condition(F) < 1e-6 must hold for every runtime field state F.
|
||||
→ algebra/versor.py::versor_condition() is the check. Fix the operator
|
||||
path or construction boundary; do not weaken the threshold.
|
||||
|
||||
❌ Normalization is allowed ONLY at:
|
||||
ingest/gate.py
|
||||
language_packs/compiler.py
|
||||
algebra/versor.py
|
||||
sensorium/*/canonical.py (signal canonicalization, pinned only)
|
||||
session/context.py (semantic anchoring; see CLAUDE.md for exact rule)
|
||||
Forbidden everywhere else, including generate/stream.py, field/propagate.py,
|
||||
vault/store.py, and all logging/telemetry paths.
|
||||
|
||||
❌ No cosine similarity, HNSW, ANN indexes, or approximate recall anywhere
|
||||
in the runtime path. Vault recall is exact and deterministic.
|
||||
|
||||
❌ No stochastic generation, opaque LLM fallbacks, or sampling in the
|
||||
deterministic cognitive path.
|
||||
|
||||
❌ No pack mutation outside the proposal-only reviewed teaching loop.
|
||||
|
||||
❌ INV-21: only allowlisted modules may call VaultStore.store(...).
|
||||
❌ INV-22/23: unmarked pack rows and store() defaults are SPECULATIVE.
|
||||
COHERENT requires an explicit stamp.
|
||||
❌ INV-24: user-facing vault.recall must pass min_status=COHERENT.
|
||||
❌ INV-29: only vault/store.py may transition epistemic_status.
|
||||
❌ INV-30: open-world determine() constructs Determined(answer=True) or
|
||||
refuses; it never asserts answer=False.
|
||||
```
|
||||
|
||||
If you believe one of these must change, **stop**. Write a proposal in
|
||||
`notes/` and do not implement it. 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 versor_condition < 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.
|
||||
|
||||
---
|
||||
|
||||
## 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, 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 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.
|
||||
|
||||
---
|
||||
|
||||
## 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, then `full` before merge.
|
||||
92
docs/handoff_template.md
Normal file
92
docs/handoff_template.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
# HANDOFF — [AGENT] — [YYYY-MM-DD]
|
||||
|
||||
<!-- Copy this file, rename to HANDOFF-[agent]-YYYY-MM-DD.md, fill in all
|
||||
sections. Do not leave placeholders. This doc is the ONLY continuity
|
||||
mechanism for stateless agents (Grok 4.3, GPT-5.5) across sessions. -->
|
||||
|
||||
## Agent and Session
|
||||
|
||||
- **Agent:** <!-- grok43 | gpt55 | claude | other -->
|
||||
- **Date:** <!-- YYYY-MM-DD -->
|
||||
- **Reasoning effort used:** <!-- high | medium | low -->
|
||||
- **Session entry point:** <!-- What task was handed to this agent? -->
|
||||
|
||||
---
|
||||
|
||||
## Smoke Suite Status
|
||||
|
||||
```
|
||||
<!-- Paste output of: core test --suite smoke -q -->
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Modules Touched
|
||||
|
||||
<!-- List every file modified, created, or deleted this session. -->
|
||||
|
||||
| File | Change type | Summary |
|
||||
|---|---|---|
|
||||
| | | |
|
||||
|
||||
---
|
||||
|
||||
## Invariants Verified
|
||||
|
||||
<!-- For each invariant relevant to this session, state how it was confirmed. -->
|
||||
|
||||
| Invariant | Check performed | Result |
|
||||
|---|---|---|
|
||||
| versor_condition < 1e-6 | | |
|
||||
| Normalization boundary | | |
|
||||
| No approximate recall | | |
|
||||
| INV-21 (VaultStore callers) | | |
|
||||
| Other (name it) | | |
|
||||
|
||||
---
|
||||
|
||||
## Tests Run
|
||||
|
||||
```bash
|
||||
# Commands run and their exit status:
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Open Tasks / Next Session Entry Point
|
||||
|
||||
<!--
|
||||
Be specific. "Continue the work" is not acceptable.
|
||||
Name the exact module, function, or ADR phase the next session should start on.
|
||||
-->
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
---
|
||||
|
||||
## Known Hazards / Do Not Touch
|
||||
|
||||
<!--
|
||||
Anything that is mid-refactor, has a known fragile state, or must not be
|
||||
edited until a specific prior step is complete.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## Architectural Decisions Made This Session
|
||||
|
||||
<!--
|
||||
Any decision that affects more than this session's diff — operator choices,
|
||||
boundary calls, ADR interpretations. Future sessions need this context.
|
||||
-->
|
||||
|
||||
---
|
||||
|
||||
## What Must Not Be Forgotten
|
||||
|
||||
<!--
|
||||
The single most important thing the next session agent must know.
|
||||
Write it as if this doc is the only thing they will read.
|
||||
-->
|
||||
Loading…
Reference in a new issue