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.
This picture is wider than it can be shown here. Move across it, or read it as text.
Drawn from its Mermaid source.
As text
Parts: - Proposed Eve behavior change - Resolve owning surface runtime policy or data boundary - Does a contract or vocabulary change? (decision) - Update types schemas clients persistence and compatibility - Change the owning implementation - Verify identity grants confirmation safety privacy and grounding - Run unit contract integration and real surface journeys - Run task-family eval cost latency and accessibility gates - Update telemetry runbooks rollout rollback and recovery evidence - Update focused docs diagrams walkthrough and generated reference - All current evidence agrees? (decision) - Canary promote and maintain Connections: - Proposed Eve behavior change to Resolve owning surface runtime policy or data boundary - Resolve owning surface runtime policy or data boundary to Does a contract or vocabulary change? - Does a contract or vocabulary change? to Update types schemas clients persistence and compatibility: yes - Does a contract or vocabulary change? to Change the owning implementation: no - Update types schemas clients persistence and compatibility to Change the owning implementation - Change the owning implementation to Verify identity grants confirmation safety privacy and grounding - Verify identity grants confirmation safety privacy and grounding to Run unit contract integration and real surface journeys - Run unit contract integration and real surface journeys to Run task-family eval cost latency and accessibility gates - Run task-family eval cost latency and accessibility gates to Update telemetry runbooks rollout rollback and recovery evidence - Update telemetry runbooks rollout rollback and recovery evidence to Update focused docs diagrams walkthrough and generated reference - Update focused docs diagrams walkthrough and generated reference to All current evidence agrees? - All current evidence agrees? to Change the owning implementation: no - All current evidence agrees? to Canary promote and maintain: yes
Show source
flowchart TD
Change[Proposed Eve behavior change] --> Own[Resolve owning surface runtime policy or data boundary]
Own --> Contract{Does a contract or vocabulary change?}
Contract -- yes --> Sync[Update types schemas clients persistence and compatibility]
Contract -- no --> Implement[Change the owning implementation]
Sync --> Implement
Implement --> Trust[Verify identity grants confirmation safety privacy and grounding]
Trust --> Tests[Run unit contract integration and real surface journeys]
Tests --> Quality[Run task-family eval cost latency and accessibility gates]
Quality --> Ops[Update telemetry runbooks rollout rollback and recovery evidence]
Ops --> Docs[Update focused docs diagrams walkthrough and generated reference]
Docs --> Release{All current evidence agrees?}
Release -- no --> Implement
Release -- yes --> Ship[Canary promote and maintain]
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.