194 lines
6.7 KiB
Markdown
194 lines
6.7 KiB
Markdown
# 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.
|