Shay 4b51ba146d chore(dev): enforce fresh-base startup guard for CORE agents

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.

2026-06-20 19:58:33 -07:00

4.5 KiB

Raw Permalink Blame History

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:

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
evals/*
calibration/*
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:

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.

Efficiency and Performance

Treat performance as part of the architecture. Slow feedback causes poor engineering decisions and hides regressions.

When touching hot paths, prefer:

backend-dispatched algebra when semantics match
import hoisting and removal of repeated structure-building
deterministic immutable caches or safe copied data
exact CGA batching/vectorization instead of approximate search
small validation lanes and bounded eval cases for iterative work

Do not improve speed by weakening invariants, skipping construction checks, adding hot-path repair, using approximate recall, or mutating shared cached state unsafely.

Security and Trust Boundaries

When touching user-controlled text, dynamic imports, filesystem paths, CLI reports, pack validators, or logs, enforce and test the trust boundary.

Required defaults:

arbitrary-code execution must be explicit and opt-in
unsafe pack IDs and path traversal must be rejected
raw user text should not be leaked in expanded logging unless local/debug is explicit
pack mutations stay proposal-only unless a reviewed path applies them
report/file writes must be bounded to caller-specified paths with clear behavior

Surface Contract

Keep these separate:

surface: selected user-facing response.
walk_surface: raw generation/manifold evidence.
articulation_surface: proposition/realizer surface.

Current policy:

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

Before starting any task, run the startup guard to ensure a fresh base:

source scripts/agent_startup.sh
# For PR-resume tasks: CODEX_ALLOW_NON_MAIN_BASE=1 source scripts/agent_startup.sh

Then use CLI suites to validate your work:

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

For a feature PR, run the smallest relevant suite and then full when practical.

Current Work Sequence

Keep CLI lanes and core eval cognition green.
Tighten hot-path backend consistency and semantics-preserving performance.
Harden pack/OOV/logging trust boundaries.
Add exact vault recall indexing/batching without approximate search.
Add Rust backend parity only after Python semantics are locked by tests.
Expand curriculum teaching after replay/eval/calibration remain deterministic.

PR Standard

Every change should state:

Capability/performance/security boundary added or protected:
Invariant protected:
CLI suite/eval run:
No hidden normalization / stochastic fallback / approximate recall / unreviewed mutation:
Trust boundary enforced when relevant:

Prefer small PRs. Do not combine baseline repair, feature work, and broad reorganization unless unavoidable.

4.5 KiB Raw Permalink Blame History