# Eve Development and Change Map

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.

```mermaid
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](./README.md) 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.

## Related

- [Runtime, tools, and actions](./runtime-tools-and-actions.md)
- [Models, quality, and evaluation](./models-quality-and-evaluation.md)
- [Eve Everywhere](../../../EVE_EVERYWHERE_TODOS_2026-08-19.md)
- [V1 Architecture](../../ARCHITECTURE.md)
- [V1 Features](../../features.md)