This map tells maintainers where Eve behavior lives and which proof should move with a change. It intentionally points to ownership seams instead of copying volatile file counts or treating every assistant-adjacent package as one monolith.
The path starts with ownership and ends with current evidence. Editing a prompt, tool label, or UI component alone is not a complete behavior change.
Source map#
| Concern | Canonical area | Typical proof |
|---|---|---|
| Shared assistant types, invocation, skills, tools, UI state | libs/oshun/shell-assistant |
Unit tests for registries/guards/state; shell integration tests. |
| Member web shell and assistant presentation | apps/oshun/web/src/components/assistant and shared shell layout |
Component tests, accessibility tests, customer Playwright journeys. |
| Builder Operations Copilot presentation | apps/oshun/admin assistant/copilot components |
Component/integration tests, admin Playwright battery and confirmation-card flows. |
| Assistant HTTP/runtime path | apps/oshun/bff/src/routes/assistant.ts and apps/oshun/bff/src/assistant |
Route, policy, router, tool, streaming, eval, and integration suites. |
| Workbench read/write/confirm tools | apps/oshun/bff/src/workbench |
Contract, persistence, authorization, idempotency, integration, and UI confirmation tests. |
| Conversation persistence | apps/oshun/bff/src/conversation |
Ordering, reconnect, retention, erasure, and event-consumer tests. |
| Iris memory | libs/iris plus BFF memory adapters |
Scope/consent/recall/privacy tests and memory journeys. |
| Sophia grounding | libs/sophia, evidence adapters, and BFF routes |
Claim/source contract, corroboration, invalidation, eval, and browser evidence tests. |
| Lilith policy | libs/lilith policy/adapters and BFF enforcement |
Persona, tone, crisis, voice-abuse, cultural-safety, and no-bypass tests. |
| Agent plane | tools/workbench-mcp/server.mjs, tools/eve-codex-agent.mjs, governed runtime |
MCP contract, lease, actor, sandbox, report, and verifier-separation tests. |
| Evaluation and maintenance | apps/oshun/bff/src/assistant/evals, docs/audits, tools/eve-* |
Deck floors, ratchets, judge validation, cost reports, and scorecards. |
Use the generated Docs Center systems catalog and repo map to resolve current project-level owners and dependency edges before changing a shared package.
Change recipes#
Add or modify an invocation point#
Update the typed registry/guard, the shell call site, context serializer, server validation, accessibility behavior, analytics event, and the relevant desktop and mobile Playwright flow. Prove out-of-scope, unauthorized, stale-context, and focus-restoration behavior.
Add a task family or routing rule#
Define the family contract, skill, toolset, grounding requirement, budget, model/escalation policy, and eval cases together. Add deterministic router tests for positive, negative, ambiguous, quoted-text, and neighboring-family language. Run the prompt hash and per-family floors.
Add a tool#
Specify typed input/output, prerequisites, actor/tenant authorization, effects and non-effects, idempotency, timeout/retry semantics, audit receipt, and UI presentation. Read tools need redaction and freshness tests. Mutation tools also need confirmation/lease, conflict, replay, transaction, and failure-recovery coverage.
Change prompts, skills, examples, or tool descriptions#
Treat all model-visible bytes as behavior. Update the string inventory/ratchet, rerun affected decks with the pinned model registry, inspect cost/latency, and record the resulting scorecard evidence. Copy review alone is not sufficient.
Change memory or grounding#
Update shared contracts, persistence/migrations, adapters, consent and deletion behavior, audit, UI disclosure, and invalidation/retraction paths. Run unit, service, integration, contract, grounded-answer evaluation, privacy/data-rights, and browser journey coverage.
Change safety or persona policy#
Version the policy, retain the no-bypass enforcement, update locale/cultural review where affected, and run the full relevant crisis/refusal/adversarial and surface suites. A presentation change can still be safety-significant if it hides disclosure, resources, or supersession state.
Change model/provider configuration#
Update the registry and configuration validation; never hardcode a silent fallback. Rebaseline only under the measurement protocol, including family floors, escalation rate, cost, latency, and provider failure behavior. Preserve rollback data.
Contract checklist#
Every new assistant contract should answer:
- Who is the actor and tenant?
- Which plane and presented identity apply?
- What is the stable request/response or event schema?
- Which values are user input, resolved server state, retrieved evidence, or model output?
- What authorization, policy, consent, budget, and confirmation checks apply?
- Is the operation idempotent, transactional, cancellable, and replay-safe?
- What receipt, audit, telemetry, and user disclosure are emitted?
- What is persisted, for how long, and how is it exported or erased?
- How does the path behave without the provider/tool/store?
- Which tests and evaluation cases block regression?
Verification matrix#
| Change type | Minimum focused automation |
|---|---|
| Pure renderer/copy with no model-visible bytes | Lint/typecheck as applicable, component test, accessibility/browser flow. |
| Model-visible copy or routing | Unit/router tests, prompt ratchet, affected family deck, browser flow. |
| Read tool | Schema/auth/redaction unit tests, service integration, task-family eval, surfaced result flow. |
| Mutation tool | All read-tool proof plus persistence/transaction/idempotency, confirmation/lease, audit, failure and Playwright coverage. |
| Memory/grounding/safety | Contract, persistence, service/integration, adversarial/evaluation, data-rights/release gates, end-to-end journey. |
| Agent/MCP | Protocol and lease tests, sandbox/actor attribution, artifact report, independent verification and recovery. |
Run expensive monorepo gates according to the repository's resource-safety policy; targeted proof is preferred while iterating, but required affected gates cannot be skipped.
Documentation obligations#
Update Eve Handbook when the identity, plane model, invariant set, or canonical reading path changes. Update the focused topic for runtime, context, safety, quality, or operational changes. Update the date-stamped audit or TODO source when the shipped/gated/backlog state changes. Regenerate and verify the Docs Center so source links, search entries, and the featured rail remain correct.