# Matrix Agent Validated — Handover Notes

**Date created:** 2026-04-25
**Status:** active checkpoint with rolling fixes

This doc explains the relationship between the lakehouse repo (this one)
and the standalone `matrix-agent-validated` checkpoint that was carved
out on 2026-04-25 to give a fresh Claude Code session a clean entry
point on a fresh box.

## The two repos

| Repo | Purpose | Branch |
|---|---|---|
| `https://git.agentview.dev/profit/lakehouse` (this) | Full project history, ~12 months, 15 crates, all phases. Source of truth for active development. | `scrum/auto-apply-19814` (PR #11) |
| `https://git.agentview.dev/profit/matrix-agent-validated` | Standalone checkpoint of the matrix-driven agent loop + Mem0-versioned pathway_memory. Single deploy unit. | `main` |

The checkpoint repo is **not a fork** — it's a deliberate snapshot. It
carries the bare minimum needed to run the agent loop on a fresh box
with no lakehouse history baggage. Bug fixes that apply to both should
land in lakehouse first, then cherry-pick (or be re-snapshotted) to
matrix-agent-validated.

## The Ansible playbook

`/home/profit/handover/ansible/` on the source box (192.168.1.176)
provisions a fresh Debian 13 box end-to-end:

```
swap → system → postgres → minio → repo → test_data → build → services → handover_note
```

The `handover_note` role renders `HANDOVER.md` on the destination from
`roles/handover_note/templates/HANDOVER.md.j2` — this is THE entry-point
file a fresh Claude Code session should read first when landing on a
deployed box. If it is missing, re-run `ansible-playbook -i inventory.ini
playbook.yml --tags handover_note`.

## Destinations — what is real, what is test

### `matrix-test` — REAL destination
- Incus container on the source machine (192.168.1.176).
- Reachable on `10.111.129.50` (incusbr0 tunnel, used by Ansible inventory),
  `192.168.2.112`, `192.168.1.32`.
- SSH: `profit:profit13`, sudo via password, key at `/root/.ssh/ironclaw`.
- Install dir: `/home/profit/matrix-agent-validated/`.
- All four services running: gateway/sidecar/observer/postgres.
- Pathway memory: 82+ traces (don't wipe `data/_pathway_memory/state.json`).
- Treat any work landing here as canonical for the checkpoint.

### `192.168.1.145` — TEST VENV ONLY, NOT A DEPLOY TARGET
- Separate VPS, hostname `ironclaw` — that's the preinstalled
  community-scripts daemon, **NOT** what this project is.
- The Ansible playbook ran here once on 2026-04-25 ~20:02 to verify
  the repo would boot on a fresh box. Got partway through the `system`
  role (swap + apt + ollama + bun + adduser) and stopped.
- **No matrix-agent-validated dir exists here.** No lakehouse services.
  No HANDOVER.md.
- **Do not push fixes here. Do not treat it as production.** If you
  find yourself debugging .145, you're in the wrong place — pivot to
  matrix-test.

## What landed today (2026-04-25 evening)

1. **Observer health-probe bug fixed** (`mcp-server/observer.ts:645`) —
   `r.json()` on the gateway's `text/plain "lakehouse ok"` response was
   throwing, causing the observer service to crash-loop every 5s.
   Fix: `r.ok ? r.text() : null`. Sealed in pathway_memory as
   `TypeConfusion:fetch-health-json`. Committed both repos.

2. **HANDOVER.md rendered on matrix-test** — the `handover_note` role
   was previously missed; one re-run rendered the doc + backed up
   `state.json` for safety.

3. **Relevance filter shipped** — `mcp-server/relevance.ts` (heuristic
   scorer) + observer `/relevance` endpoint + `scrum_master_pipeline.ts`
   wiring (env opt-out via `LH_RELEVANCE_FILTER=0`, threshold via
   `LH_RELEVANCE_THRESHOLD`). 9 unit tests green. Drops adjacency-pollution
   chunks from matrix retrieval before the reviewer LLM sees them.

## Still queued (from the rendered HANDOVER.md on matrix-test)

- Audit-consensus → retire wire (auto-retire poisoned pathways when
  observer rejects)
- Mode router (port LLM Team patterns from source `/root/llm_team_ui.py`)
- Pgvector backend (third option alongside Parquet + Lance, RAG/training
  focused)
- Local-model scratchpad daemon (continuous summarizer for active context)

## Commands a fresh session should run first

```bash
# On the source box (192.168.1.176)
git -C /home/profit/lakehouse log --oneline -10                # what's recent
cat /home/profit/lakehouse/docs/MATRIX_AGENT_HANDOVER.md       # this file
cat /home/profit/lakehouse/docs/SCRUM_MASTER_SPEC.md           # scrum loop spec

# On matrix-test (real destination)
ssh -i /root/.ssh/ironclaw profit@10.111.129.50 \
  'cat /home/profit/matrix-agent-validated/HANDOVER.md'         # cold-start guide
ssh -i /root/.ssh/ironclaw profit@10.111.129.50 \
  'curl -s http://localhost:3100/health'                        # smoke test
```