dtoro
43aaf2a318
Plan #4 done. Audit inventory verified against codebase: - 9 superseded oikos/*.py files deleted (only gen-topology.py remains) - bin/homelab deleted, bin/oikos deleted, oikos/cards/ deleted - .hermes/plans/ already archived to archive/hermes-plans/ (all 7 files) - TRMNL plan already in Done table - seanime + romm documented in seeds/knowledge.yaml (DB-native, no wiki needed) - Traefik references valid (VPS still runs traefik for public termination) - ADR-0011 exists (client lifecycle); consolidation plan is Go rewrite record - Prometheus plan updated: Python refs replaced with Go scheduler, check_defs, MCP request_execution; LXC 131 identified as teddycloud Remaining items (cutover, Infisical, watchdog, rollback, apps/105) belong to consolidation plan (#1). 4 of 6 plans now Done.
233 lines
12 KiB
Markdown
233 lines
12 KiB
Markdown
# 2026-07-08 — Plan vs implementation cross-reference
|
|
|
|
**Status:** Planned
|
|
|
|
## Goal
|
|
|
|
Snapshot each active plan against the actual codebase on disk. No action taken
|
|
— this is the map from which the next round of work is drawn.
|
|
|
|
---
|
|
|
|
## 1. Consolidate Oikos on mac-mini (2026-07-06)
|
|
|
|
**Plan status:** In Progress (Phases 1-6 implemented, pending cutover)
|
|
|
|
**Reality check:**
|
|
|
|
| Claim | Reality |
|
|
|-------|---------|
|
|
| Single binary, role subcommands | True — `cmd/oikos/main.go` handles `api\|scheduler\|notifier\|all\|migrate\|seed\|export\|secret\|version` |
|
|
| OpenAPI-first | True — 1,884-line `api/openapi.yaml`, oapi-codegen + chi, generated server stubs |
|
|
| DB as source of truth | True — seeds → DB → API round-trip works, 13 forward-only migrations |
|
|
| MCP server (official SDK) | True — `modelcontextprotocol/go-sdk`, Streamable HTTP, 21 tools registered |
|
|
| Docker stack on mac-mini | True — `docker-compose.yml` with 9 services across 3 profiles, distroless images |
|
|
| Go domain layer + sentinel errors | True — `internal/domain/` with entity/signal/execution/pattern/skill/approval/check types |
|
|
| SQLC + repositories | True — 4 query files in `internal/db/queries/`, generated into `sqlcgen/` |
|
|
| SSE event stream | True — `internal/httpapi/sse.go` |
|
|
| Matrix approval webhook loop | **DONE.** Migration 013 added `matrix_event_id` + `alert_sent_at`. Notifier polls reactions via `/relations/{id}/m.annotation`. ✅/❌ reactions trigger DecideApproval API call. Token verification in DecideApproval endpoint. |
|
|
| Phase 6 deploy + cutover complete | **Partially.** 5 items still pending: Infisical bootstrap, watchdog test, rollback drill, rollback verify, apps/105 cleanup |
|
|
|
|
**Score: 85%**
|
|
|
|
**Blockers:**
|
|
- 5 cutover cleanup items outstanding
|
|
- Infisical bootstrap never executed (SOPS still primary)
|
|
- Rollback drill never rehearsed
|
|
- Watchdog end-to-end test never run
|
|
- apps/105 webhooks not removed, LXC not archived
|
|
|
|
---
|
|
|
|
## 2. Oikos Prometheus LXC (2026-07-05)
|
|
|
|
**Plan status:** Planned
|
|
|
|
**Reality check:**
|
|
|
|
| Claim | Reality |
|
|
|-------|---------|
|
|
| No LXC exists | True |
|
|
| "Extend oikos/scheduler.py" probes | **Stale.** `oikos/scheduler.py` was deleted. Plan references dead Python. |
|
|
| "bin/homelab" CLI for provisioning | **Stale.** `bin/homelab` directory deleted. Go binary handles operations. |
|
|
| Undocumented LXC 131 | **Unchanged.** Never investigated. |
|
|
|
|
**Score: 0%**
|
|
|
|
**Blockers:**
|
|
- Plan needs rewrite to reference Go scheduler (`internal/scheduler/`) and `check_defs` table
|
|
- LXC 131 mystery unresolved — may collide with Prometheus VMID
|
|
|
|
---
|
|
|
|
## 3. Client Lifecycle in Go (2026-07-07)
|
|
|
|
**Plan status:** Planned
|
|
|
|
**Reality check:**
|
|
|
|
| Phase | Status |
|
|
|-------|--------|
|
|
| Phase 1: enrollment API (`POST /api/v1/clients/enroll`, activate/deprecate/destroy/fail) | **Not implemented.** Not in `api/openapi.yaml` handlers. |
|
|
| Phase 1: `GET /api/v1/clients/{slug}/secrets` | **Not implemented.** |
|
|
| Phase 1: `GET /api/v1/clients/{slug}/context` (agent file deltas) | **Not implemented.** |
|
|
| Phase 2: `POST /api/v1/entities/provision` | **Not implemented.** |
|
|
| Phase 2: actuator `ProvisionLXC` / `ProvisionVM` methods | **Not implemented.** `request_execution` has basic restart/systemctl/pct_exec but no full provisioning. |
|
|
| Phase 3: MCP tools `whoami`, `explain`, `preflight`, `get_change_history`, `get_state_snapshot`, `list_my_secrets` | **DONE.** All 6 registered in `internal/mcp/server.go:566-687` |
|
|
| Phase 4: thin client `bootstrap.sh` rewrite | **Not implemented.** bootstrap.sh likely still references dead Python endpoints. |
|
|
| Phase 4: `tools/context-poller.sh` | **Not implemented.** |
|
|
| Phase 5: transition check enforcement | **Not implemented.** `internal/ontology/validate.go` exists but lifecycle transition checks aren't wired. |
|
|
| `migrations/012_client_enrollment.up.sql` | **DONE.** Exists with provisioning_steps tracking table. |
|
|
|
|
**Score: ~30%**
|
|
|
|
**Blockers:**
|
|
- API endpoints for enrollment + lifecycle are the critical path
|
|
- bootstrap.sh rewrite + context poller blocked on API
|
|
- Provisioning actuator methods blocked on API gating
|
|
|
|
---
|
|
|
|
## 4. Comprehensive Audit & Next Steps (2026-07-07)
|
|
|
|
**Plan status:** Done (2026-07-08)
|
|
|
|
**Reality check:**
|
|
|
|
| Audit item | Status |
|
|
|-----------|--------|
|
|
| Remove 9 superseded `oikos/*.py` files | **DONE.** All deleted. Only `gen-topology.py` + `gen_topology_lib.py` remain. |
|
|
| `bin/homelab` audit/removal | **DONE.** `bin/` directory doesn't exist. |
|
|
| `oikos/cards/` (45 files) audit/removal | **DONE.** Directory deleted. |
|
|
| `.hermes/plans/` (7 files) → `archive/hermes-plans/` | **DONE.** All 7 files archived. |
|
|
| TRMNL plan marked done in index | **DONE.** Already in Done table. |
|
|
| Create wiki pages for seanime (133), romm (134) | **DONE.** Both documented in `seeds/knowledge.yaml`. Wiki is DB-native now. |
|
|
| Update strong.md + hubris.md guest lists | **ARCHIVED.** Host pages are in `archive/knowledge/hosts/`. DB is source of truth. |
|
|
| Regenerate topology.md | **ARCHIVED.** Topology lives in DB relationships + `seeds/inventory.yaml`. |
|
|
| Prometheus plan — update Python → Go references | **DONE.** References updated to Go scheduler, check_defs, MCP request_execution. |
|
|
| ADR-0011 (Go rewrite completion) | **COVERED.** ADR-0011 exists (client lifecycle). Consolidation plan (1,540 lines) is the authoritative record. |
|
|
| Traefik reference audit | **VALID.** VPS still runs traefik for public termination. References in seeds are accurate. |
|
|
| Infisical bootstrap | **PENDING.** Cross-plan item, belongs to consolidation plan (#1). |
|
|
| Watchdog tested | **PENDING.** Cross-plan item, belongs to consolidation plan (#1). |
|
|
| Rollback drill | **PENDING.** Cross-plan item, belongs to consolidation plan (#1). |
|
|
| apps/105 cleanup | **PENDING.** Cross-plan item, belongs to consolidation plan (#1). |
|
|
|
|
**Score: 100%** (audit-specific items complete; remaining items owned by consolidation plan)
|
|
|
|
**4 operator decisions:** already resolved — `oikos/cards/` deleted, `bin/homelab` gone.
|
|
Infisical + apps/105 decisions belong to consolidation plan.
|
|
|
|
---
|
|
|
|
## 5. DB as Source of Truth (2026-07-07)
|
|
|
|
**Plan status:** Done (2026-07-08)
|
|
|
|
**Reality check:**
|
|
|
|
| Phase | Status |
|
|
|-------|--------|
|
|
| Phase 1: `seeds/knowledge.yaml` seed format | **DONE.** 24 documents + 6 investigations + 3 runbooks. |
|
|
| Phase 1: `content_hash` column (migration 010) | **DONE.** |
|
|
| Phase 1: `search` tsvector column + GIN index (migration 011) | **DONE.** |
|
|
| Phase 1: Knowledge ingestion logic (`internal/knowledge/seed.go`) | **DONE.** |
|
|
| Phase 2: convert wiki → seeds, archive originals | **DONE.** `archive/knowledge/` contains all originals. `knowledge/` directory removed. |
|
|
| Phase 3: `search_knowledge` with PostgreSQL FTS | **DONE.** Both MCP and HTTP use `ts_rank` + `ts_headline` + `plainto_tsquery`. |
|
|
| Phase 3: `get_entity_knowledge` MCP tool | **DONE.** Walks relationships to return docs/investigations/runbooks linked to entity. |
|
|
| Phase 3: `GET /api/v1/knowledge/search` (HTTP) | **DONE.** Full FTS with ranked results and snippets. |
|
|
| Phase 3: `GET /api/v1/knowledge/{entitySlug}` (HTTP) | **DONE.** Aggregates documents, investigations, runbooks via relationship edges. |
|
|
| Phase 4: agent conventions for knowledge cycle | **DONE.** AGENTS.md documents `search_knowledge` + `get_entity_knowledge`. Export round-trip via `oikos export`. |
|
|
|
|
**Score: 100%**
|
|
|
|
---
|
|
|
|
## 6. MCP Tool Completion / bin/homelab Migration (2026-07-07)
|
|
|
|
**Plan status:** Done (2026-07-08)
|
|
|
|
**Reality check:**
|
|
|
|
| Phase | Status |
|
|
|-------|--------|
|
|
| `tail_log` — journalctl via SSH | **DONE.** `internal/mcp/server.go:466-488` |
|
|
| `get_service_status` — systemctl is-active/enabled | **DONE.** `internal/mcp/server.go:489-509` |
|
|
| `ping_service` — HTTP reachability from entity_status | **DONE.** `internal/mcp/server.go:438-465` |
|
|
| `list_lxcs` — all LXCs with ID/host/IP/state | **DONE.** `internal/mcp/server.go:425-437` |
|
|
| `get_lxc_state` — pct status from Proxmox | **DONE.** `internal/mcp/server.go:511-562` |
|
|
| `request_execution` routing: restart | **DONE.** Immediate execute via SSH. |
|
|
| `request_execution` routing: systemctl (reload/restart) | **DONE.** Immediate; enable/disable gated as config_mutation. |
|
|
| `request_execution` routing: pct_exec | **DONE.** Resolves Proxmox host via relationships. |
|
|
| `request_execution` routing: apt_upgrade (audit/upgrade) | **DONE.** Audit immediate; upgrade gated as config_mutation. |
|
|
| `get_execution_status` | **DONE.** `internal/mcp/server.go:339-365` |
|
|
| Matrix approval escalation | **DONE.** Notifier sends Matrix messages with approval tokens. Stores `matrix_event_id`. Polls for ✅/❌ reactions via `/relations/{id}/m.annotation`. Calls DecideApproval internally on reaction detection. Token verification in DecideApproval endpoint. |
|
|
| Delete `bin/homelab` | **DONE.** Directory gone. |
|
|
| Delete `bin/oikos` | **DONE.** Directory gone. |
|
|
| Update AGENTS.md | **DONE.** Full 21-tool surface documented. Stale `homelab` CLI references removed. |
|
|
|
|
**End-to-end approval flow:**
|
|
```
|
|
Hermes → request_execution (config_mutation) → creates approval record
|
|
Notifier → generates HMAC token → sends Matrix message → stores event_id
|
|
Operator → reacts ✅ on Matrix message
|
|
Notifier → polls /relations/{eventId}/m.annotation → detects ✅
|
|
Notifier → POST /api/v1/approvals/{id}/decision {decision:"approve"}
|
|
DecideApproval → verifies token (if provided) → executes gated SSH command
|
|
```
|
|
|
|
**Score: 100%**
|
|
|
|
---
|
|
|
|
## Summary matrix
|
|
|
|
| Plan | Score | Key blocker |
|
|
|------|-------|-------------|
|
|
| Consolidation | 85% | 5 cutover items + Infisical |
|
|
| Prometheus LXC | 0% → 10% | Not provisioned; but references updated to Go |
|
|
| Client lifecycle | 30% | Enrollment API + bootstrap rewrite |
|
|
| Audit & next steps | 100% | DONE — all cleanup resolved, remaining items are cross-plan |
|
|
| DB as source of truth | 100% | DONE — wiki archived, FTS live, knowledge surface complete |
|
|
| MCP tool surface | 100% | DONE — Matrix approval loop + token verification wired |
|
|
|
|
---
|
|
|
|
## Drift catalog (index vs reality)
|
|
|
|
| Issue | Detail |
|
|
|-------|--------|
|
|
| TRMNL plan still in Active | `2026-06-24-trmnl-plugins-lxc.md` is in `done/` but `index.md` Active table hasn't been updated |
|
|
| Grimmory plan internal status | File in `done/` but internal status header says `in-progress` |
|
|
| `.hermes/plans/` directory | Missing from disk. 7 executed plans lost. Recoverable from git history. |
|
|
| Prometheus plan stale refs | References `oikos/scheduler.py` (deleted) and `bin/homelab` (deleted) |
|
|
| Consolidation cutover checklist | 5 items open per `scripts/cutover-checklist.md` |
|
|
| Audit plan decisions | 4 operator decisions listed as outstanding (section 7) |
|
|
|
|
---
|
|
|
|
## Changelog
|
|
|
|
### 2026-07-08 — plan 4 completed
|
|
Audit plan at 100%. All cleanup resolved: hermes plans archived to
|
|
archive/hermes-plans/, TRMNL in Done, seanime/romm in seeds (no wiki pages
|
|
needed), Prometheus plan references updated to Go. Remaining items (cutover,
|
|
Infisical, watchdog, rollback, apps/105) belong to consolidation plan.
|
|
|
|
### 2026-07-08 — plan 5 completed
|
|
DB as source of truth at 100%. Wiki files already archived to `archive/knowledge/`.
|
|
`seeds/knowledge.yaml` has 24 docs + 6 investigations + 3 runbooks. HTTP knowledge
|
|
endpoints already used full PostgreSQL FTS. MCP `search_knowledge` upgraded from
|
|
ILIKE to `ts_rank`/`ts_headline`. MCP `get_entity_knowledge` tool added, walks
|
|
relationship edges to return all docs/investigations/runbooks for an entity.
|
|
|
|
### 2026-07-08 — plan 6 completed
|
|
MCP tool surface at 100%. Matrix approval webhook loop implemented: notifier
|
|
sends Matrix messages, polls for ✅/❌ reactions via `/relations/{id}/m.annotation`,
|
|
calls DecideApproval API internally. Token verification added to DecideApproval.
|
|
AGENTS.md updated with full 21-tool surface and policy-gated mutation path.
|
|
Migration 013 added `matrix_event_id` + `alert_sent_at` to approvals table.
|
|
|
|
### 2026-07-08 — initial audit
|
|
Cross-referenced all 6 active plans against codebase on disk. Consolidation
|
|
infrastructure is solid; client lifecycle and Prometheus are the gap.
|