4b51ba146d
Add scripts/agent_startup.sh — a sourced bash guard that prevents stale-base worktrees from silently replaying or creating conflict PRs. Root cause: PR #844 was opened from a worktree whose HEAD was behind origin/main. The resulting replay produced a conflict-laden PR that required manual reconciliation (see PR #847). ## Behaviour Default (new implementation task): HEAD must equal origin/main Working tree must be clean → source scripts/agent_startup.sh PR-resume task: CODEX_ALLOW_NON_MAIN_BASE=1 source scripts/agent_startup.sh origin/main must be a strict ancestor of HEAD (enforced via merge-base) Debug-only dirty override: CODEX_ALLOW_DIRTY=1 source scripts/agent_startup.sh ## Steps performed by the script 1. git fetch origin --prune 2. Print HEAD / branch / origin/main / merge-base 3. Fail if dirty (unless CODEX_ALLOW_DIRTY=1) 4. Fail if HEAD != origin/main (unless CODEX_ALLOW_NON_MAIN_BASE=1) 5. In resume mode, verify origin/main is ancestor of HEAD via merge-base 6. Print diff --name-status vs origin/main 7. Verify uv exists 8. uv sync --frozen only when uv.lock is present 9. Print final git status ## Escape hatches CODEX_ALLOW_NON_MAIN_BASE=1 PR-resume, ancestry enforced CODEX_ALLOW_DIRTY=1 Debug/WIP sessions, documented in session log ## Validation bash -n scripts/agent_startup.sh → OK git diff --check → OK (no trailing whitespace) shellcheck not available locally; shebang is bash, bash -n passed ## Non-goals Does not touch runtime, evals, reports, teaching proposals, packs, policy, identity, recall, vault, field, algebra, or serving paths.
138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
# 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
|
|
```
|