executus/CLAUDE.md

# executus — developer & agent guide

> ⚠️ **This project is vibe-coded** (AI-authored, human-steered). See `README.md`.

executus is a **batteries-included base for LLM agent harnesses**, layered
strictly above [majordomo]. majordomo is the lean substrate (agent loop, `llm`
types, providers, media, parse/failover/tiering). executus is the opinionated
layer majordomo deliberately omits. **executus requires no majordomo changes** —
it decorates `llm.Model` and wraps `majordomo/agent.Agent`.

[majordomo]: https://gitea.stevedudenhoeffer.com/steve/majordomo

## North star

A brand-new project imports executus, does a little setup, and is most of the way
to agentic capabilities. The mechanism is **one shipped default per seam**:
`executus.New()` (once the runtime lands) is agentic with zero host wiring; the
same builder lets a serious host swap each default for its own implementation and
register its own tools.

Two consumers define the envelope:

- **mort** (heavy) — Discord, mortbux, media, MySQL/GORM, DB-backed convar config,
  saved skills, audit, scheduling, run-critic.
- **gadfly** (light) — a CI PR-reviewer Docker image, env-var configured, running
  an N-models × M-lenses structured-output swarm. Needs model fleet, lanes,
  bounded runs, structured output, fan-out, a few read tools — and **none** of the
  batteries.

That spread is why executus is **tiered**: a light host imports core only; a heavy
host opts into batteries.

## Module & layering

One module `gitea.stevedudenhoeffer.com/steve/executus`, `go.mod` = **majordomo +
stdlib only** (no gorm/redis/discordgo/cgo). A second nested module
`contrib/store` carries the SQLite dependency so the core never inherits it.

```
CORE (majordomo + stdlib):
  config/   ConfigSource seam (+ env default)            [P0 ✓]
  lane/     bounded fair-share worker pool               [P0 ✓]
  fanout/   programmatic N×M swarm                       [P0 ✓]
  deliver/  output egress seam (+ Discard/Stdout)        [P0 ✓]
  identity/ caller identity seams                        [P0 ✓]
  run/      run.Executor is RUNNABLE: model-resolve +    [P2 core ✓]
            toolbox + majordomo loop + compaction +
            run-bounding (V10 detached timeout) + step/
            audit observers + Budget gate; RunnableAgent
            DTO + nil-safe run.Ports. Palette delegation
            WIRED (skill__/agent__ tools, C0). Follow-ups:
            wire Critic/Checkpointer/Delivery, Phases     [C0b]
  dispatchguard/  loop/depth/fan-out caps                [P0 ✓]
  pendingattach/  attachment dedupe                      [P0 ✓]
  tool/     registry + 3-stage permissions + ssrf        [P1 ✓]
  model/    config-driven tier resolution over majordomo [P1 ✓]
            (convar->config.Source; UsageSink/TraceSink seams; GenerateWith[T]
             structured output — no separate structured/ pkg)
  llmmeta/  shared meta-LLM helper over model/            [P1 ✓]
  compact/  context compactor (WithCompactor hook)       [P2 ✓]
  tools/    generic tool library: Register (think/now/    [P3 ✓]
            cite, zero-config) + RegisterMeta (classify/
            extract_entities/summarize) + RegisterStore
            (kv_*/file_*, default static quota); seams in
            research_providers.go/file_storage.go/
            kv_storage.go/quota_provider.go. End-to-end
            "agent calls a tool" test green. Remaining
            (deferred): web/net/compose groups + backends

BATTERIES (opt-in siblings, each nil-safe + a default):
  persona/   Agent noun + Storage seam + builtin loader [P4 ✓]
             + ToRunnable() bridge to run.RunnableAgent +
             Memory default (host: chatbot/commands/personalization)
  skill/     Skill noun + LEAN SkillStore (lifecycle/    [P4 ✓]
             versions/schedule, NOT mort's 60-method
             monster) + ToRunnable + Memory default
  audit/     run.Audit Sink + Writer + queryable Memory  [P4 ✓]
             default (skillaudit Storage iface; GORM stays in mort)
  critic/    two-tier timeout watchdog (run.Critic) +    [P4 ✓]
             Escalator policy seam + ExtendOnce default
  schedule/  generic cron Runner (Tick/Loop over a wired [P4 ✓]
             Due/Run/Mark/Next; no cron grammar of its own)
  checkpoint/ CheckpointStore + run.Checkpointer handle  [P4 ✓]
             (throttled Save/Complete/Fail) + Memory
  budget/    DBBudget rolling-7d + NoOp (run.Budget);    [P4 ✓]
             BudgetStorage iface + Memory default

contrib/store/   SECOND module (+ modernc.org/sqlite):   [P4 ✓]
  pure-Go SQLite impls of ALL store seams: budget +
  persona + skill + audit (JSON-blob+indexed cols,
  round-trip tested). CI proves the driver lands HERE,
  not in the core go.sum.

NOTE: critic/checkpoint executor wiring (run.Ports.Critic /
.Checkpointer call sites) is a P2 follow-up — the batteries +
defaults exist ahead of that wiring.
```

### The one architectural move

The kernel must import **no battery**. In mort today, `agentexec` imports
`agents`, `agentcritic`, and `skillaudit` directly — those three up-pointing edges
get inverted into nil-safe `run.Ports` interfaces (`PaletteSource`, `Critic`,
`Audit`) plus a `RunnableAgent` DTO. Everything else is wide-but-shallow
repackaging.

## Invariants (enforced in CI)

- The core module builds with **majordomo + stdlib only**. `go.sum` must not
  contain gorm/redis/discordgo/sqlite/gin.
- No `core/*` package imports a `battery/*` package.
- Standard Go gates: `go build`, `go vet`, `go test -race`, `go mod tidy` clean.

## Extraction roadmap

P0 module + zero-coupling moves + core seams (this) → P1 tool registry + model →
P2 run kernel + Ports inversion → P3 generic tools + defaults → P4 persona/skill
redesign + batteries + SQLite store → P5 gadfly-on-core canary (examples/reviewer ✓) → P6
rewire mort + tag v0.1.0. The mort-side rewrite reuses mort's existing
`mort_*_adapters.go` wall as the host adapter layer.

## Conventions

- **Keep `README.md`, this `CLAUDE.md`, and `examples/` in sync with every change,
  in the SAME commit.** No aspirational docs: when you add/rename a package, change
  a seam or a default, or alter the public API, update the docs and the relevant
  example so they always reflect reality (mirrors majordomo's house rule). The
  status markers in the tier map above must track what's actually landed.
- Mirror majordomo's house style: gofmt; check errors immediately and wrap with
  `fmt.Errorf("...: %w", err)`; `// Why:` comments where rationale isn't obvious;
  hermetic tests (majordomo's fake provider; no network in the default suite).
- Every seam is an interface with a nil-safe accessor and a shipped default.
- Keep the core seam surface small and stable — push churn into tools and host
  adapters, not core interfaces.