docs: add MATRIX_AGENT_HANDOVER notes + cross-link from SCRUM_MASTER_SPEC

The matrix-agent-validated repo split + Ansible deploy pipeline are
otherwise undocumented in this repo. This new doc explains:
- the relationship between lakehouse and matrix-agent-validated
- where the playbook lives and what it provisions
- the critical distinction: matrix-test (10.111.129.50 Incus container)
  is the REAL destination, while 192.168.1.145 is a smoke-test VPS only
  (partial deploy, no services, do not treat as production)
- what landed today (observer fix, HANDOVER.md render, relevance filter)

Added a cross-link block at the top of SCRUM_MASTER_SPEC.md so the
canonical scrum handoff doc points at the new MATRIX_AGENT_HANDOVER doc.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/MATRIX_AGENT_HANDOVER.md

@@ -0,0 +1,103 @@
+# 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
+```

docs/SCRUM_MASTER_SPEC.md

@@ -4,6 +4,12 @@
 **Last iter:** 9 (2026-04-24)
 **Branch commit head:** `f4cff66` (ADR-021 Phase D fix)
 
+> **2026-04-25 — see also `docs/MATRIX_AGENT_HANDOVER.md`** for the
+> standalone `matrix-agent-validated` repo split + the Ansible playbook
+> that deploys it. Note: VPS at 192.168.1.145 is a TEST VENV ONLY
+> (partial deploy); the real destination is the `matrix-test` Incus
+> container at 10.111.129.50.
+
 This doc is the single handoff artifact for the scrum-master + auto-apply + pathway-memory loop built during 2026-04-24 sessions. A fresh Claude Code session reading this + `docs/DECISIONS.md` (ADR-020 and ADR-021 specifically) + `MEMORY.md` should have the same context as the session that wrote it.
 
 ## 1. What the loop is