chris/OSVauco
1
0
Fork 0
Code Issues 1 Pull Requests Actions 2 Packages Projects Releases Wiki Activity
330e3ada1f
OSVauco/docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md

6.7 KiB
Raw Blame History

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:
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:
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

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

Assistant:
registrert

Turn two

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:

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:
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.