AGENTS.md · diff

git:20260914.2094d9b to git:20260914.b6e3b89

135 added, 403 removed. Audit A to A.

# AGENTS.md

- > Code-root navigation map for AI agents (Claude Code, Cursor, Codex CLI,

- > etc.) working in this repository. The pattern is adapted from OpenClaw's

- > `AGENTS.md` convention.

- >

- > Human-oriented documentation lives under:

- > - `docs/` — internal design notes

- > - `site/src/app/docs/` — public site (`mangowhoiscloud.github.io/geode/docs`)

- >

- > This file is the LLM entry point. Read this first when changing code.

+ Shared contributor instructions for coding agents working on GEODE.

+ Claude Code reads this same file through `CLAUDE.md`'s `@AGENTS.md` import;

+ do not duplicate the contract in a host-specific entry point.

## Project at a glance

- - **What**: a self-hosting autonomous-agent harness whose runtime is an AgenticLoop (`while tool_use`).

- - **Language**: Python 3.12+, type-hinted, uv-managed.

- - **Layout**: three top-level packages with one implementation direction.

- - `core/` — GEODE runtime and operator surface.

- - `evals/` — measurement and audit consumers of the runtime.

- - `evolve/` — scaffold search and hill-climbing over runtime evidence.

- - **Quality bar**: ruff, mypy, pytest plus a prompt-hash ratchet. CI breaks on red.

- - **Public site**: `site/` (Next.js 16 static export, deployed to GitHub Pages).

+ GEODE is a self-hosting autonomous-agent harness built around an AgenticLoop

+ (`while tool_use`). Python 3.12+, type-hinted, managed with uv.

+ - `core/` — runtime and operator surface; does not depend on `evals` or `evolve`.

+ - `evals/` — measurement and audit consumers of the runtime.

+ - `evolve/` — scaffold search and hill-climbing over runtime/evaluation evidence.

+ - `site/` — Next.js static-export public documentation.

+ - `docs/` — internal architecture, contracts, and contributor guidance.

+ Run `uv sync` for a local development environment. CLI entry points are declared

+ in `pyproject.toml`; do not install globally or restart a service without scope.

## Choose the instruction owner

- This file is a contributor navigation map, not the runtime's complete system

- prompt. Its short task-to-source routing follows the same role as the

- [Dioxus agent guide](https://github.com/DioxusLabs/dioxus/blob/ada3b67c73c1c5484dd2e8408cb21c470b200423/AGENTS.md).

+ This is a contributor navigation map, not GEODE's runtime system prompt.

Read the relevant owner, then inspect its caller and test before editing.

| Need | Owner and actual consumer |

|---|---|

- | Repository changes, tests and merge procedure | `AGENTS.md` → `CLAUDE.md` / `docs/workflow.md`; read by the coding agent, not automatically loaded by GEODE |

+ | Repository changes, tests, and integration | This file → [workflow](docs/workflow.md) → `.claude/skills/geode-workflow/`; read by the coding agent, not automatically loaded by GEODE |

| Runtime identity and conduct | Four selected `GEODE.md` sections → `core/agent/system_prompt.py`; persona-off and audit modes omit identity |

- | Shared completion and failure behavior | `core/llm/prompts/router.md` agentic suffix → prompt composition, including identity overrides; pins in `core/llm/prompts/__init__.py` |

+ | Shared completion and failure behavior | `core/llm/prompts/router.md` agentic suffix → prompt composition, including identity overrides; hashes in `core/llm/prompts/__init__.py` |

| Task-specific runtime guidance | `.geode/skills/` → `use_skill`; `.agents/skills/` is the separate development scaffold |

- For example, a missing cache counter starts at the provider adapter, then the

- durable usage event and Harbor export—not by making an unknown value zero in

- the report. Reproduce that path with a fixture, preserve the failed result,

- and rerun the relevant checks. Local success is not remote CI success; the

- guarded merge procedure lives in `.agents/skills/geode-gitflow/`.

+ `CLAUDE.md` is Claude Code project context, not a replacement for its system

+ prompt or an enforcement mechanism. Actual permission checks, hooks, and

+ sandboxing remain separate. The shared-file pattern follows the

+ [official Claude Code import guidance](https://code.claude.com/docs/en/memory#agentsmd).

- For generated public release metadata, read

- `site/src/data/geode/sot.ts` (auto-generated by `npm run sync-stats`); today it

- owns only the package version and sync date.

+ ### Task-to-source routing

+ | Task | Read first |

+ |---|---|

+ | Ordinary development | [Evidence-first workflow](docs/workflow.md) and `.agents/skills/geode-workflow/` |

+ | Branches, PRs, merge, cleanup | `.agents/skills/geode-gitflow/`; `.github/PULL_REQUEST_TEMPLATE.md` |

+ | Abstraction, naming, types, schemas, tests, compatibility | [Naming conventions](docs/architecture/naming-conventions.md) and `.agents/skills/geode-code-conventions/` |

+ | Architecture/extensibility program | [Extensibility roadmap](docs/architecture/extensibility-roadmap.md), the single execution SOT for GAP IDs, order, status, acceptance, and closure evidence |

+ | Package ownership | [Package classification](docs/architecture/package-classification.md) |

+ | Coding-agent state, recovery, workspace/process limits | [Coding runtime authority](docs/architecture/coding-runtime-authority.md) before adding a record or store |

+ | Model/provider support, OAuth, capabilities | `core/llm/model_catalog.py`, provider/adapters call path, and `.agents/skills/model-onboarding/` |

+ | Prompt text or assembly | `.agents/skills/prompt-writing/`, `core/agent/system_prompt.py`, and loop context assembly |

+ | Usage/cache/cost and artifact accounting | [Usage accounting](docs/architecture/usage-accounting.md) and the workflow observability reference |

+ | Benchmark execution, attempts, publication | Generated `docs/eval/index.json` and `.agents/skills/geode-eval/` |

+ | Agent-World comparisons | [Comparison contract](docs/eval/agent-world-comparison-contract.md) and `.agents/skills/agent-world-benchmark/`; do not label its undisclosed wrapper `no loop` |

+ | Test-time compute / best-of-N / verifier scheduling | `.agents/skills/stanford-test-time-compute/`; separate candidate width, repair depth, measurement replication, and promotion authority |

+ | `/geo` or `/grill` | `.agents/skills/geo/` or `.agents/skills/grilling/`; runtime behavior stays in the corresponding `.geode/skills/` contract |

+ | Public docs, generated maps, visual design | [Official docs generation](docs/architecture/official-docs-generation.md), `site/DESIGN.md`, and `site/src/app/docs/` |

+ | Release and packaging | `.agents/skills/geode-changelog/`, `.agents/skills/geode-distribution/`, and GitFlow's release path |

+ Other task-specific development skills are indexed in

+ [the scaffold catalog](docs/scaffold-skills.md). `.claude/skills/` uses relative

+ per-skill aliases to `.agents/skills/`, so both hosts read the same bytes.

+ A same-named development skill links to its runtime contract instead of copying it.

+ ## Module map

+ Inspect the changed module, its callers, and mirrored tests. Cross-cutting work

+ must trace every affected boundary; this table is routing, not an API census.

+ | Area | Entry and responsibility |

+ |---|---|

+ | `core/agent/` | `loop/agent_loop.py` drives turns; `loop/models.py` owns termination reasons; `system_prompt.py` assembles static/dynamic context; `sub_agent.py` manages child execution |

+ | `core/llm/` | `adapters/` owns async SDK clients; `providers/` owns provider shaping/auth helpers; `fallback.py` and loop/router callers own application retry policy |

+ | Prompt content | `prompts/router.md` and opt-in `prompts/reviewer.md` are hash-pinned; `prompt_assembler.py` is only the math-output helper, not a second system assembler |

+ | `core/tools/` | Handler in its category module → `registry.py` registration → `definitions.json` schema; deferred loading is adapter-owned (`core/llm/tool_defer.py`) |

+ | `core/mcp/` | `manager.py` delegates config, connections, invocation/trace, and lifecycle to concrete owners; client tools use raw server names, not external-host `mcp__geode__*` names |

+ | `core/memory/` | `context.py` assembles Identity/Profile/Org/Project/Session; `goals.py` owns explicit persistent objectives, not advisory Plan or automatic Plan-and-Execute |

+ | `core/hooks/` | `system.py` owns events and trigger/interceptor behavior; trace registration through bootstrap |

+ | `core/wiring/` | Bootstrap, explicit service injection, serve, shutdown, and request-local binding/reset |

+ | `core/server/` | CLI↔daemon IPC, capability negotiation, and lifecycle |

+ | `core/skills/` | `skills.py`: bundled → global-user → project discovery; `use_skill` loads a selected body on demand, not trigger-based automatic injection |

+ | `core/cli/`, `core/gateway/` | Typer/slash operator surface; messaging adapters and lane queues |

+ | `core/scheduler/`, `core/orchestration/` | Scheduling and TaskGraph; do not infer either from a conversational plan |

+ | `core/audit/` | Per-call diagnostics; preserve usage coverage and audit-mode boundaries |

+ | `evals/petri/` | `cli_audit.py` → runner/audit mode/judge schema; seeds and judge dimensions own their evaluation contracts |

The generated architecture inventory lives at

`site/src/data/geode/architecture-baseline.json`. Refresh it with

`uv run python scripts/architecture_baseline.py --update`; CI uses `--check`.

The current snapshot records 582 production Python files,

714 test Python files,

86 tool definitions, and

57 `RuntimeEvent` members.

- For architecture and extensibility work, read

- `docs/architecture/extensibility-roadmap.md`. It is the single execution SOT

- for GAP IDs, merge order, status, acceptance criteria, and closure evidence in

- that program. Older architecture audits and dated plans are design evidence,

- not competing status ledgers.

- The current package classification and product-shell migration boundary lives

- in `docs/architecture/package-classification.md`.

- Use `docs/workflow.md` as the canonical workflow summary and

- `.claude/skills/geode-workflow/` as the progressive-disclosure execution

- scaffold. It is shared with Claude Code and supersedes the older issue-first

- workflow.

- For abstraction level, module/file naming, Python type and class selection,

- persisted schema identity, test placement, site code, or versioning decisions,

- read `docs/architecture/naming-conventions.md` and use

- `.agents/skills/geode-code-conventions/`.

- For benchmark execution, evaluation artifact audits, research-question

- framing, attempt lineage, or trajectory publication, start at the generated

- `docs/eval/index.json` and use `.agents/skills/geode-eval/`. Claude Code sees

- the same tracked skill through the relative `.claude/skills/geode-eval` alias.

- For `/geo`, generative-search visibility, citation readiness, or GEO

- measurement, use `.agents/skills/geo/` and treat

- `docs/eval/geo-visibility.md` as the suite profile. Run the deterministic site

- preflight before proposing a score-bearing engine run; live commercial-engine

- repetitions require a frozen run spec and explicit approval. Runtime behavior

- lives separately in `.geode/skills/geo/`.

- For `/grill` or dependency-aware decision clarification, use

- `.agents/skills/grilling/`; runtime interview behavior lives in

- `.geode/skills/grilling/`. Candidate trees select structure before side

- effects and do not imply shared-state MCTS/LATS execution.

- For test-time compute, best-of-N, verifier-aware scheduling, inference-program

- search, or GEODE/Eco²/SIL/Crucible comparisons, use

- `.claude/skills/stanford-test-time-compute/`. Read its lecture analysis before

- mapping the concepts to current code, and keep candidate width, repair depth,

- measurement replication, and promotion authority separate.

- For Agent-World comparisons, three-suite MCP-Mark/BFCL V4/tau2 profiles,

- paired thin-runtime controls, or `mean_accuracy@8` publication, use

- `.claude/skills/agent-world-benchmark/` and treat

- `docs/eval/agent-world-comparison-contract.md` as the canonical comparison

- contract. Never label the paper's undisclosed in-house wrapper as `no loop`.

- ## Module map

- Read the module you are about to change. If a section says "read this first",

- do it. Cross-cutting changes require reading all related modules.

- ### `core/agent/`

- The agentic loop. `while(tool_use)` primitive that drives every turn.

- - `loop/agent_loop.py` — `AgenticLoop`. No round limit by default

- (`DEFAULT_MAX_ROUNDS = 0` → unlimited; time-budget controlled),

- with a closed `TerminationReason` alphabet defined in `loop/models.py`.

- Auto-escalation was removed in v0.90.0. The model itself emits the

- termination signal.

- - `system_prompt.py` — `build_system_prompt()`. `PROMPT_CACHE_BOUNDARY`

- is the opening `<dynamic_context>` tag separating STATIC and DYNAMIC blocks.

- - `sub_agent.py` — `SubAgentManager`: max depth 1 (no recursion), session cap 15,

- global Lane concurrency 50 (`core/wiring/container.py`).

- Read this first when changing termination paths, loop bounds, or system prompt

- assembly.

- For coding-agent state ownership, recovery, workspace/process limits, review,

- and cross-domain task lookup, read

- [`docs/architecture/coding-runtime-authority.md`](docs/architecture/coding-runtime-authority.md)

- before adding a runtime record or store.

- ### `core/llm/`

- LLM router, providers, prompt assembly, hashing.

- - `prompt_assembler.py` — math-output helper used by the active prompt path.

- Production assembly lives in `core.agent.system_prompt` plus AgenticLoop

- per-round context; the legacy `PromptAssembler` class was removed.

- - `providers/` — low-level quota, cache, identity, and native-tool shaping

- consumed by `adapters/`; app-owned retry policy lives in `fallback.py` and

- the loop/router call sites. The sync client layer and

- `providers/openai.py` were deleted 2026-07-29 — LLM completion is

- async-only and every SDK client is owned by `adapters/`.

- - `providers/anthropic.py` — quota, prompt-cache + breakpoint helpers,

- native-tool and defer shaping.

- - `providers/glm.py` — GLM 5.x family. Context window 202_752 (not 200_000).

- Thinking gate (`thinking.type="off"|"none"`).

- - `providers/codex.py` — OAuth token resolution + async client.

- - `prompts/__init__.py` — `_PINNED_HASHES`. Karpathy P4 ratchet.

- - `prompts/router.md` — router-system and agentic-suffix sections, both hash-pinned.

- - `prompts/reviewer.md` — opt-in read-only adversarial review, hash-pinned.

- - `postprocess/html_output.py` — strips OpenAI data-URL HTML.

- Read this first when changing prompt content (will break the hash ratchet),

- adding a provider, or touching cache/tool-choice/streaming behaviour. Also read

- `.claude/skills/prompt-writing/` before creating or editing model-facing prompt

- text: GEODE prompts use metadata/behavioral clauses, not direct identity

- assertions such as `You are ...`.

- For token/cache accounting, cost output, or usage artifacts, read

- [`docs/architecture/usage-accounting.md`](docs/architecture/usage-accounting.md).

- It maps the actual fields and validators and distinguishes normalized zero,

- missing final usage, completed-call lower bounds, and cost/billing authority.

- ### `core/tools/`

- The current tool counts and definition/execution/schema parity are generated in

- `site/src/data/geode/architecture-baseline.json`. Deferred loading lives at the

- provider adapters (official `defer_loading` plus hosted `tool_search`), not in

- the registry.

- - `base.py:35` — `Tool` Protocol.

- - `core/llm/tool_defer.py` — `TOOL_SEARCH_ALWAYS_LOADED` policy.

- - `definitions.json` — single SOT for tool metadata.

- - Category modules: `file_tools.py`, `memory_tools.py`, `data_tools.py`,

- `computer_use.py`, `web_tools.py`, `profile_tools.py`, etc.

- Read this first when adding a tool: define handler in a category module,

- register in `registry.py`, expose schema in `definitions.json`.

- ### `core/mcp/`

- MCP server adapters plus 25K result guard.

- - `manager.py` — `MCPServerManager` compatibility facade over concrete

- configuration, connection, discovery/invocation, trace, and lifecycle owners.

- - `config_catalog.py`, `connection_pool.py`, `tool_runtime.py`,

- `lifecycle.py` — the facade's single-purpose collaborators.

- - `stdio_client.py` — STDIO transport. Declares protocol revision

- `2025-06-18`, records the server-negotiated revision in

- `server_protocol_version`, and fail-loud-rejects revisions outside the

- supported classic set (ADR-014; SDK pinned `mcp>=1.28,<2`). Live E2E

- 2026-07-28: loopback negotiation + agent-level MCP dispatch verified on the

- subscription backend.

- - Client-path MCP tools surface under their **raw server-side names** — the

- `mcp__geode__*` prefix appears only on external hosts consuming geode-mcp.

- - Calendar / Steam / etc. adapters.

- ### `core/memory/`

- 5-tier context hierarchy. Vault. Bidirectional learning.

- - `context.py:32` — `ContextAssembler`. Five tiers: Identity / Profile / Org /

- Project / Session.

- - `goals.py` — explicit multi-turn Goal projection in `sessions.db`. This is a

- persistence/termination envelope, not `CognitiveState.goal`, advisory Plan,

- TaskGraph, or an automatic Plan-and-Execute engine.

- - `vault/` — agent-produced artifact storage.

- Read this first when changing memory tiers, context budgets, or the 200K

- absolute token guard.

- For evidence-first research, the public runtime skill is

- `.geode/skills/deep-researcher/SKILL.md`. Ordinary research stays bounded;

- only an explicitly requested persistent objective may call `create_goal`.

- ### `core/hooks/`

- The current `HookEvent` count and member inventory are generated in

- `site/src/data/geode/architecture-baseline.json`.

- - `system.py` — `HookEvent` enum and `HookSystem` class. Three trigger modes:

- `trigger`, `trigger_with_result`, `trigger_interceptor`.

- Read this first when adding an event or wiring an interceptor.

- ### `core/wiring/`

- Bootstrap, serve, shutdown. Renamed from `core/lifecycle/` in v0.87.

- - Manages ContextVar injection order.

- - Cold-start lazy loading (cumulative −258ms, warm −86%, v0.85-89).

- ### `core/server/`

- IPC daemon. Thin CLI ↔ daemon protocol.

- - `ipc_server/poller.py` — receives `client_capability` messages (v0.84).

- Includes `{is_tty, width}` so the daemon can suppress ANSI escapes for

- non-TTY clients.

- - `ipc_client.py` — thin-CLI side. Calls `_send_client_capability()` on connect.

- ### `core/audit/`

- Per-call diagnostics for Petri audits (v0.92+).

- - `diagnostics.py` — `CallDiagnostic` dataclass. cache_read/write, cost

- breakdown, latency, audit_mode flag.

- ### `core/skills/`

- Runtime SkillRegistry. Distinct from the cross-host `.agents/skills/`

- development scaffold and its relative `.claude/skills/` aliases.

- - `skills.py` — `SkillLoader` / `SkillRegistry`, 3-tier discovery

- (bundled → global user `~/.geode/skills/` → project `.geode/skills/`).

- - `use_skill` tool loads a skill body on demand (Progressive Disclosure Tier 2).

- Keep runtime behavior under `.geode/skills/`. When a same-named

- `.agents/skills/` scaffold exists, it must link to that runtime contract rather

- than copy it; Claude Code consumes the scaffold through a relative per-skill

- alias under `.claude/skills/`.

- ### `core/scheduler/`, `core/orchestration/`

- Natural-language scheduling, task graph (TaskGraph).

- ### `core/cli/`

- Typer commands and thin CLI surface. Slash commands.

- ### `core/gateway/`

- Slack / Discord / Telegram adapters. Lane queue concurrency.

- ### `evals/petri/`

- Petri × GEODE alignment audit (v0.92+).

- - `cli_audit.py` — `geode-eval audit` Typer wrapper.

- - `seeds/` — 20 GEODE-specific seeds organised across 3 tiers

- (critical / auxiliary / info), spanning autonomy, calibration,

- compute_use, efficiency, exploratory, reasoning, research.

- - `judge_dims/` — judge dimension catalog. Default `subset`

- (`geode_judge_subset.yaml`, 22 dim = 19 default-38 string subset +

- 3 PR-0 context-management JudgeDimension dicts) or `full` (38 dim).

- - `runner.py`, `audit_mode.py`, `judge_schema.py`, `optimize.py`.

- ## Workflow constraints

- These are absolute. `CLAUDE.md` remains the full development scaffold and

- source of truth for rationale. `docs/workflow.md` summarizes the executable

- evidence-first workflow, and `.claude/skills/geode-workflow/` holds the

- Claude Code compatible scaffold.

- ### Non-negotiables

- - **Worktree required**: never commit directly on `main` or `develop`. Use

- `git fetch origin`, then create implementation and ordinary roadmap

- worktrees from `origin/develop`. Within the architecture program, the sole

- base exception is the roadmap's tracking-only `DONE` PR: it starts from

- `origin/main`, targets `main`, and is followed by a CI-gated

- `main -> develop` sync PR. Other main-maintained tracking documents use their

- own dedicated `origin/main` worktree under the repository's tracking rules.

- - **Canonical sync first**: use the current `main` head for `main -> develop`

- when it is mergeable under strict up-to-date protection. Do not put a copied

- or fast-forwarded `main` head behind the trusted sync-branch prefix.

- - **Trusted sync branch naming**: when conflicts or strict ancestry block the

- canonical head, use `sync/main-into-develop-`. Its head must be the exact

- two-parent merge of current `origin/develop` and `origin/main`, in that order.

- Rerun the trust resolver immediately before merge; `scripts/merge_pr.py`

- rechecks the same proof against live remote tips without weakening protection.

- - **No branch switching inside a worktree**: never use `git checkout` to reuse

- a checkout for another branch. Allocate or enter the correct worktree instead.

- - **Fetch before allocating branches**: run `git fetch origin` before creating

- a worktree. Do not claim a branch needs sync from commit counts alone; verify

- content with `git diff A B --stat`.

- - **Protect other sessions**: never delete a worktree or branch held by another

- active worktree. If an `.owner` file exists and does not belong to the current

- session, leave it alone.

- - **No direct push to `main` or `develop`**: open a PR and wait for CI.

- - **No tracking-doc edits from feature/develop**: project tracking documents are

- maintained from `main` unless the user explicitly asks otherwise. The

- standing user-authorized exception is limited to the roadmap-only readiness,

- claim, GAP-registration, reconciliation, and full-ledger audit PRs for

- `docs/architecture/extensibility-roadmap.md` defined in that file's §0.3.

- - **No CHANGELOG omission**: every functional commit updates `CHANGELOG.md`

- under `[Unreleased]`. Documentation-only changes do not need a changelog

- entry.

- - **Prompt hashes are pinned**: changing any prompt under `core/llm/prompts/`

- requires updating `_PINNED_HASHES` in the same commit.

- - **Prompt wording avoids identity assertions**: model-facing prompt text must

- follow `.claude/skills/prompt-writing/`. Prefer metadata/behavioral clauses

- (`Agent:`, `Runtime:`, `Mode:`, `Scope:`) over `You are ...`, `Act as ...`,

- or similar roleplay framing.

- - **No `# type: ignore` proliferation**: fix the type error.

- - **No live tests by default**: tests marked `-m live` require explicit user

- approval because they may spend money or call external services.

- - **No unsupported SDK/backend assumptions**: for third-party capability

- claims, verify against primary docs or source before shipping behaviour.

- ### Codex Operating Loop

- Use `docs/workflow.md` and `.claude/skills/geode-workflow/` for code changes

- unless the user explicitly asks for a different process. The compact loop below

- mirrors that scaffold.

- 0. **Orient**: read this file, then read the module-map entry for the files you

- will touch. Check `git status --short --branch`.

- 1. **Worktree**: if you are on `main` or `develop`, create a feature worktree

- from the fetched `origin/develop` tip. Use fetched `origin/main` only for

- explicitly main-maintained tracking work, including the roadmap's

- tracking-only `DONE` path. If you are already in the correct worktree,

- continue there. Do not switch branches in-place.

- 2. **GAP audit**: search before editing. Confirm whether the requested

- behaviour already exists, partially exists, or is absent.

- 3. **Plan gate**: for non-trivial work, state the smallest measurable plan.

- Simple bug fixes and docs fixes may proceed directly after the GAP audit.

- 4. **Implement**: keep changes scoped. Prefer existing helpers and local

- patterns. Do not revert unrelated dirty work.

- 5. **Verify**: run the narrowest relevant tests first, then broaden when the

- blast radius justifies it. Functional changes should usually run ruff, mypy

- for touched modules, and targeted pytest.

- 6. **Docs sync**: update `CHANGELOG.md` for functional changes. Update public

- docs only when behaviour or user-facing workflow changes.

- 7. **PR prep**: summarize Summary / Why / Changes / Verification. Use

- `feature -> develop` squash merge when merging; use `develop -> main`

- merge after syncing `main -> develop`.

- 8. **Post-merge cleanup**: after a feature PR merges, run

- `uv run python scripts/check_repo_hygiene.py free-merged-worktree --pr <N> --worktree <path>`

- from outside the target worktree. It verifies the merged PR tree, branch

- ancestry, remote head, clean checkout, and `.owner` before deleting the

- remote branch, worktree, and squash-only local branch in that order.

- Never hand-force-delete an unverified or another session's worktree.

- ### Quality Gates

- Use the [verification reference](.agents/skills/geode-workflow/references/verification-gates.md)

- for scope, commands, and evidence reuse. `scripts/preflight.sh` runs broad local

- checks; required CI on the actual PR head remains the merge gate. Report exact

- results and skipped checks without hiding non-zero exit codes.

- ### PR Body

- Use [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md).

- GitFlow owns integration-specific additions; do not maintain another template.

- ## Where to look for things

- | Question | File |

- |---|---|

- | What does a tool do? | `core/tools/definitions.json` and the category module |

- | What models can I use? | `core/llm/providers/<provider>.py` |

- | Why a layer? | `core/agent/loop/agent_loop.py` plus `docs/architecture/` |

- | Which code convention applies? | `docs/architecture/naming-conventions.md` plus `.agents/skills/geode-code-conventions/` |

- | How are hooks wired? | `core/hooks/system.py` plus `core/wiring/bootstrap.py` |

- | How are usage, cache, and costs represented? | `docs/architecture/usage-accounting.md`, `core/llm/token_tracker.py`, and `core/llm/usage_store.py` |

- | Petri audit run? | `evals/petri/cli_audit.py` |

- | Site docs? | `site/src/app/docs/**` |

- ## Tests

- Each subsystem has `tests/test_<name>.py`. Live tests are marked `-m live`.

+ The inventory owns file/tool/event counts, not executable test-case totals.

+ Use `uv run pytest --collect-only` for the latter. Public release metadata in

+ `site/src/data/geode/sot.ts` is generated by `npm run sync-stats` and owns only

+ the package version and sync date.

- Generated test file/LOC inventory lives in

- `site/src/data/geode/architecture-baseline.json`. Use

- `uv run pytest --collect-only` for the executable test-case count;

- `site/src/data/geode/sot.ts` does not own test inventory.

+ ## Working contract

- ## Frontier sources

+ These are repository rules. Detailed procedures live with their owners above;

+ do not turn an incident-specific fix into an unconditional rule for every task.

- These external systems shape GEODE's design. When you change something here,

- verify whether the new shape still echoes its source.

+ 1. **Scope and inspect.** Check `git status --short --branch`, ownership, and

+ actual call paths. Review/status requests stay read-only. For implementation,

+ classify existing/partial/absent behavior and state the smallest measurable

+ plan. Simple fixes need no separate planning document. Resolve ambiguous

+ deletion scope before deleting; preserve unrelated dirty work.

+ 2. **Isolate.** Fetch before allocating from the authorized remote base. Never

+ commit on `main`/`develop`, switch branches inside a worktree, or remove

+ another session's worktree/branch. Preserve mismatched `.owner` markers.

+ Implementation and ordinary roadmap work start from `origin/develop`;

+ main-maintained tracking work uses `origin/main`. The roadmap's §0.3 owns

+ its narrow readiness/claim/GAP/reconciliation/full-ledger exceptions.

+ 3. **Implement at the owner.** Reuse existing registries and helpers. Trace

+ producer → field/state → reader → decision, including explicit/automatic

+ input branches and refresh/invalidation. Process services cross constructors,

+ grouped config, or `ToolContext`; reserve `ContextVar` for request-local

+ identity, diagnostics, state, and caches. See the workflow's

+ [contract checks](docs/workflow.md#contract-checks) for boundary verification.

+ 4. **Preserve prompt boundaries.** `GEODE.md` is the runtime SOUL surface, not

+ a contributor rulebook. Use the prompt-writing skill for authored text;

+ GEODE's local style is English metadata/behavioral clauses rather than

+ `You are ...`/`Act as ...`. This is not a vendor requirement or permission

+ to translate user content. Prompt-file edits update `_PINNED_HASHES` in the

+ same commit and test the relevant identity/override/audit modes.

+ 5. **Verify honestly.** Run narrow checks first, broaden for changed risk or

+ failures. Use the [verification gates](.agents/skills/geode-workflow/references/verification-gates.md)

+ for ruff, mypy, pytest, prompt integrity, and independent review. Do not hide

+ non-zero exits behind pipes/chaining, disable tests to manufacture green,

+ add blanket type ignores, or report stubs/partial work as complete.

+ Unknown measurements are not zero; latest evidence is not promoted evidence.

+ 6. **Ground external claims.** Verify SDK/backend/model capabilities against

+ primary docs/source. Unsupported or ambiguous acceptance stays guarded;

+ live tests, paid calls, publication, global installs, and service changes

+ require authorization. An explicit persistent objective is required before

+ creating a goal; ordinary research remains bounded.

+ 7. **Synchronize docs.** Functional commits update `[Unreleased]` in

+ `CHANGELOG.md`. Update affected code-to-doc mappings, public behavior docs,

+ and generated mirrors through their owner commands. Do not hand-maintain

+ parallel metrics or bump a version without an authorized release.

+ 8. **Integrate through GitFlow.** No direct push to protected branches.

+ Feature → develop is squash; develop → main is merge after canonical

+ main → develop synchronization. Verify content with `git diff A B --stat`,

+ not commit counts alone. Use current main directly if mergeable; otherwise

+ `sync/main-into-develop-*` must be the exact two-parent merge of current

+ develop then main. `scripts/merge_pr.py` rechecks live tips, exact PR-head

+ required CI, and trust before merge. Missing/stale checks never prove green;

+ local success is not remote CI success.

+ 9. **Clean up with proof.** After an owned feature PR merges, run

+ `scripts/check_repo_hygiene.py free-merged-worktree` from outside that

+ checkout. Follow GitFlow's owner/cleanliness/merge-proof checks; never

+ force-delete an unverified worktree. Merge does not authorize release.

- - Claude Code (Anthropic). While-tool-use loop, CLAUDE.md scaffolding, 4-tier

- memory.

- - OpenClaw. Gateway-centric routing, Lane Queue, Session isolation,

- Policy Chain, plugin discovery.

- - Karpathy autoresearch (2026-03). Fixed wall-budget, frozen scoreboard, git

- monotone ratchet, token-economic loop, simplicity criterion.

- - Prime Agent (2026-08). RLM-native programmable context, continual harness

- state, persistent subagents, and native-harness evaluation discipline.

- - Original/upstream implementations. Pin the native task, prompt, workspace,

- verifier, and result authority before adding a benchmark integration or

- platform adapter; do not claim equivalence without parity evidence.

- - Hermes Agent (NousResearch). llms.txt / llms-full.txt dual index pattern.

- - Diátaxis. Documentation 4-quadrant model.

+ ## Source discipline

- ## See also

+ The navigation pattern borrows from the pinned

+ [Dioxus agent guide](https://github.com/DioxusLabs/dioxus/blob/ada3b67c73c1c5484dd2e8408cb21c470b200423/AGENTS.md):

+ route to the owner, then verify fields, calls, failure branches, and tests in

+ current code. Numbered architecture documents are topics, not execution order.

+ Older audits and dated plans are evidence, not competing status ledgers.

- - `CLAUDE.md` — development workflow scaffold.

- - `GEODE.md` — runtime identity and conventions.

- - `site/DESIGN.md` — public site visual system.

- - `site/src/app/docs/reference/external-references` — cited frontier systems

- with applied patterns.

+ For frontier comparisons, use `.agents/skills/frontier-harness-research/` and

+ the [cited source inventory](site/src/app/docs/reference/external-references).

+ Pin the native task, prompt, workspace, verifier, and result authority before

+ claiming benchmark or harness equivalence. Do not substitute a scoped test,

+ replay, or successful tool call for verifier-backed task completion.