seshat: Instructions file for Codex

Agent Instructions — Seshat

This file provides guidance for AI agents (Seshat, Claude Code, Codex, or similar) working on this repository. Read it before making any changes.

---

Project overview

seshat is an open-source Go AI agent runtime. It has no concept of users, organizations, or billing — those live in the products built on top of it: SeshatOS (local) and SeshatCloud (multi-tenant), both separate repositories. The engine exposes three entry points: cmd/cli (terminal), cmd/grpc (gRPC server), and pkg/sdk (Go SDK for embedding).

---

Known bugs to fix first

TODO.md lists errors found by reading the code: behavior that is wrong, security gaps, and features that exist but are never connected. Read it before touching compaction, hooks, runtime events, project instructions or the auto-mode classifier, and do not build on top of an item that is listed there without fixing or noting it.

---

Build and test

Always run these before finishing:

go build ./...          # must pass — no exceptions
go vet ./...            # must pass — no exceptions
go test -race ./...     # must pass — fix failures, do not skip
golangci-lint run ./... # pass or explain why an existing violation is pre-existing
gofmt -w .              # always run after editing Go files

If go test fails, investigate and fix the root cause. Do not disable tests or add t.Skip() to work around failures.

---

Branching strategy

main        production-ready, tagged releases only
  └── dev   stable integration — all work lands here first via PR
        └── <type>/<slug>   one branch per issue

• Always branch off dev.
• Never commit or push directly to main.
• Never commit or push directly to dev.
• All work must land through a PR: <type>/* → dev, then dev → main.
• PRs target dev. The only allowed PR into main is dev → main for final validation by maintainers.
• Direct PRs from topic branches into main must be closed without merge.
• The Gate CI check (Build + Test + Lint) must be green before any PR can merge.
• Name branches <type>/<short-slug> where <type> is one of feat, fix, docs, refactor, test, chore, perf, or ci.