docs(handoff): record Emma canonicalization baseline
This commit is contained in:
parent
c7c96efd12
commit
330e3ada1f
193
docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md
Normal file
193
docs/handoffs/EMMA-CANONICALIZATION-2026-09-19.md
Normal file
|
|
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user