profit/lakehouse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
lakehouse/docs/MATRIX_AGENT_HANDOVER.md
root e1ef185868
Some checks failed
lakehouse/auditor 1 blocking issue: todo!() macro call in tests/real-world/scrum_master_pipeline.ts
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>
2026-04-25 23:54:42 -05:00

4.7 KiB
Raw Blame History

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

# 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