docs(handoff): record Emma canonicalization baseline

2026-09-19 13:56:48 +00:00 · 2026-09-19 13:56:48 +00:00 · 330e3ada1f
commit 330e3ada1f
parent c7c96efd12
1 changed files with 193 additions and 0 deletions
--- a/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md
+++ b/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md
@ -0,0 +1,193 @@
+# 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.