OSVauco/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md

# Emma Canonicalization Handoff

## Scope

This handoff begins the controlled, phase-locked Emma canonicalization program.

The program uses one named phase per Gemini session, normally limited to
45–60 minutes. Each phase must start from command-proven Git and runtime
state, stay inside its authorized scope, end with tests/diff/status, and stop.

## Verified Baseline

- **Repository:** `~/OSVauco`
- **Branch:** `feat/opax-domain-decouple`
- **Local HEAD:** `c7c96efd12bb3f3cdcfe9309e7683f0d01c16366`
- **Subject:** `fix(deploy): include MCP requirements in Cloud Build context`
- **Date:** `2026-09-19T12:39:31+00:00`
- **Local worktree status:** clean when this handoff was prepared
- **Remote status:** local `c7c96ef` was ahead of `origin/feat/opax-domain-decouple` before the handoff push

## Verified Public Health

- `https://opax.vauco.no/` returned HTTP 200 with valid TLS.
- `opax-mcp` authenticated health returned `status: ok`.
- The MCP health response reported the expected internal Ollama configuration.
- The public OPAX site and MCP service are distinct deployed services.

## Active Runtime

### OPAX MCP

- **Cloud Run service:** `opax-mcp`
- **Active revision:** `opax-mcp-00200-gcp`
- **Traffic:** 100%
- **Image:**

```text
us-central1-docker.pkg.dev/propane-will-491900-m5/osvauco-repo/opax-mcp@sha256:8687cd7489e789c17f6a56985191d6d924fc03d35d28c78bf94fea8b17b83091
```

### OPAX Web

- **Cloud Run service:** `opax-web`
- **Active revision:** `opax-web-00014-fnw`
- **Traffic:** 100%
- **Revision creation:** `2026-09-19T00:21:32.201043Z`
- **Image:**

```text
us-central1-docker.pkg.dev/propane-will-491900-m5/osvauco-repo/opax-web@sha256:27105067393c607d97a4c44fffe54bdf1da6ce7a6dd662e114f039fc04d69892
```

## Failed Acceptance Test

The live OPAX browser chat completed a basic response but failed the same-session
conversation-continuity acceptance test.

### Turn one

```text
User:
Husk dette testtokenet kun i denne samtalen:
OPAX-EMMA-1909.
Svar bare: registrert

Assistant:
registrert
```

### Turn two

```text
User:
Hva var testtokenet jeg ba deg huske?

Assistant:
Jeg har ikke godkjent VAUCO-kontekst i denne chatten ennå...
```

This is a failed same-session continuity acceptance test.

## Verified Local Source Path

The checked-out source contains the intended same-session history path:

```text
Browser conversation state
→ OPAX Web frontend request history
→ OPAX Web BFF
→ MCP JSON-RPC arguments.history
→ opax-mcp run_emma
→ _normalize_emma_history
→ CanonicalEmma.run
→ _ollama_chat
→ Ollama messages payload
```

Verified local implementation characteristics:

- `opax-mcp/server.py` `run_emma` passes normalized request history to `canonical_emma.run`.
- `_normalize_emma_history` retains only `user` and `assistant` roles.
- Blank messages are removed.
- The latest 40 historic messages are retained.
- `opax-mcp/emma_adapter.py` `CanonicalEmma.run` forwards history to its injected chat function.
- `opax-mcp/server.py` `_ollama_chat` places one canonical system prompt first, then history, then the current user prompt.
- Firestore/Morphic persistence is not part of the current same-session `run_emma` route.

## Unverified Runtime Facts

The following must remain explicitly marked as unverified until supported by
runtime payload evidence, deployed-source provenance, or focused tests:

- Whether active `opax-web` sends history in the real browser request.
- Whether active `opax-web` includes the local history implementation.
- Whether live Ollama receives the expected second-turn message sequence.
- Whether the active model uses valid history correctly after receiving it.
- Firestore/Morphic persistent-memory wiring.
- INCU ticket storage and execution wiring.
- Emma access to Gitea/Git context.
- Perplexity connector correctness.

## Architecture Boundaries

- OPAX Web is the authenticated UI and BFF.
- `opax-mcp` is the controlled model and tool gateway.
- Emma is the canonical runtime/agent.
- Same-session history, persistent memory, INCU ticketing, Git context, Git writes, and Perplexity connectivity are separate phases.
- The browser and model must not receive raw credentials, unrestricted terminal access, or direct infrastructure authority.
- Consequential actions require explicit human approval, resolved targets, structured arguments, audit evidence, and a visible result.
- Historic client messages may contain only `user` and `assistant` roles; historic `system` and `tool` roles must not reach the model payload.

## Phase Plan

1. **PHASE 0** — Runtime truth baseline.
2. **EMMA-SESSION-001A** — No-network session-history regression tests.
3. **EMMA-SESSION-001B** — Browser/BFF second-turn history-payload proof.
4. **EMMA-SESSION-001C** — Controlled release and live token acceptance.
5. **EMMA-PERSIST-001** — Authenticated, user-scoped Firestore session persistence.
6. **INCU-TICKET-001** — INCU ticket proposal/review workflow; no execution.
7. **EMMA-GIT-READ-001** — Structured read-only Git/Gitea context.
8. **EMMA-PATCH-001** — Patch proposal and allowlisted local validation.
9. **EMMA-GIT-WRITE-001** — Explicit approval-gated Git write lane.
10. **MCP-PERPLEXITY-001** — Separate Perplexity connector repair.

## Immediate Next Ticket

### EMMA-SESSION-001A

**Goal:** Add no-network regression coverage for the existing local history path.

Required test coverage:

1. `run_emma` normalizes and forwards valid historic `user` and `assistant` messages.
2. Historic `system`, `tool`, malformed, blank, and non-string-content entries are excluded.
3. `_ollama_chat` creates this exact final ordering:

```text
canonical system prompt
→ validated user/assistant history
→ current user prompt exactly once
```

**Out of scope:**

- Production code changes.
- Firestore or Morphic persistent memory.
- Git/Gitea access.
- INCU ticket execution.
- Commit, push, build, or deployment.
- Cloud Run, IAM, secrets, VPC, billing, or DNS changes.

**Completion condition:** Local no-network tests pass, diff is reviewed, and a human explicitly decides whether to commit.

## New Gemini Session Contract

Every Gemini session must:

1. Work on exactly one named phase.
2. Begin with raw output from:
   - `pwd`
   - `git branch --show-current`
   - `git log -1`
   - `git status --short`
3. Stop if the branch is not `feat/opax-domain-decouple`.
4. Stop if unexpected modifications are present.
5. Use exact source paths and line ranges.
6. Mark unsupported claims as `UNVERIFIED`.
7. Never invent Git SHAs, Cloud Run revisions, image digests, deployments, or test results.
8. End with actual test results, exact diff, Git status, confirmed facts, unverified facts, and a hard stop.

Commit, push, build, deployment, Firestore writes, Gitea writes, Cloud Run changes,
IAM changes, secret changes, VPC changes, and infrastructure actions require separate
explicit approval.

## EMMA-SESSION-001B Result

**Status:** PASS

The live OPAX browser same-session conversation-continuity acceptance test
passed without a code change, test change, deployment, or runtime
configuration change.

### Live evidence

```text
Turn 1

User:
Husk dette testtokenet kun i denne samtalen:
OPAX-EMMA-1909.
Svar bare: registrert

Assistant:
Registrert.

Turn 2

User:
Hva var testtokenet jeg ba deg huske?

Assistant:
OPAX-EMMA-1909.
```

### Confirmed

- Emma preserved and used same-session conversation context through the active
  OPAX application path.
- The live application path is functioning for this acceptance test:

```text
opax.vauco.no
→ opax-web
→ opax-mcp
→ CanonicalEmma
→ Ollama
→ OPAX browser response
```

- No production code change was justified by this passing result.
- No OPAX web deployment was justified by this passing result.
- No MCP deployment was justified by this passing result.

### Still unverified

- Exact browser/BFF JSON payload for the second turn.
- Exact cause of the earlier failed token test.
- Browser refresh behavior.
- New-chat behavior.
- Cross-session persistence.
- Firestore/Morphic persistent-memory wiring.
- INCU ticket workflow wiring.
- Emma Git/Gitea access.
- Perplexity connector compatibility.

## Next Phase

### EMMA-SESSION-001C

**Goal:** Verify repeatability and clearly distinguish same-session context from
persistent memory.

**Allowed:** Browser-only manual acceptance checks and read-only documentation.

**Out of scope:**

- Production code changes.
- Tests or test-environment changes.
- Firestore/Morphic memory implementation.
- Git/Gitea access.
- INCU ticket execution.
- Build, deployment, Cloud Run, IAM, secrets, VPC, billing, and DNS changes.

**Acceptance checks:**

1. Run a new same-session token test with a different token.
2. Confirm the second turn returns that new token.
3. Refresh the browser only after recording whether the same conversation is
   still visible.
4. Start a new chat and confirm Emma does not claim to remember the prior chat
   unless such persistence is explicitly implemented and authorized.
5. Record each result as PASS, FAIL, or UNVERIFIED.