diff --git a/docs/MATRIX_AGENT_HANDOVER.md b/docs/MATRIX_AGENT_HANDOVER.md new file mode 100644 index 0000000..2004962 --- /dev/null +++ b/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 +``` diff --git a/docs/SCRUM_MASTER_SPEC.md b/docs/SCRUM_MASTER_SPEC.md index 021fe27..2de95f5 100644 --- a/docs/SCRUM_MASTER_SPEC.md +++ b/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