From 330e3ada1f13c42b5efdb0f7c1de7a4979e23e72 Mon Sep 17 00:00:00 2001 From: Chris Christiansen Date: Sat, 19 Sep 2026 13:56:48 +0000 Subject: [PATCH] docs(handoff): record Emma canonicalization baseline --- .../EMMA-CANONICALIZATION-2026-09-19.md | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md diff --git a/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md b/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md new file mode 100644 index 0000000..d3a67ae --- /dev/null +++ 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.