interlearn

modernize priority P2 effort M wave 2

What it does: A shell-only Claude Code plugin (no MCP server, no Python, no daemon) that builds a cross-repo index of solution docs across the monorepo. index-solutions.sh walks /docs/solutions/.md under hub/plugins/services/infra/docs, parses heterogeneous YAML frontmatter (category|problem_type, date|created|date_resolved), derives module identity from file path (not frontmatter), and emits docs/solutions/INDEX.md (human) + index.json (machine). One skill exposes three modes: /index (rebuild + report missing-frontmatter gaps), /search (Phase 1 substring match over index.json title/tags/problem_type/module/path with exact-tag>title>path ranking, Phase 2 grep fallback when <5 hits), and /audit (cross-references bd closed beads against reflect sprint_artifacts + solution-doc bead-ID mentions to surface documentation-coverage gaps). A fail-open SessionEnd hook re-indexes in the background when cwd is inside the monorepo (3-marker detection: .beads/+plugins/+hub/).

Rationale: The purpose is sound and the audit/coverage loop is genuinely valuable institutional-memory plumbing that nothing else fully owns (the producer-side compound skill writes docs; only interlearn checks whether closed work left them behind). Keep the concept. But two concrete problems justify modernize over keep: (1) Correctness/portability bug — paths are hardcoded inconsistently across three files: SKILL.md and the hook fast-path assume /root/projects/Interverse, AGENTS.md test commands reference /home/mk/projects/Demarch, and the repo actually lives at /Users/sma/projects/Sylveste/interverse. The hook’s general walk-up saves it from total breakage, but the skill’s literal bash /root/projects/Interverse/plugins/interlearn/scripts/index-solutions.sh path will fail outright on this machine. (2) The retrieval layer is pre-frontier: flat substring+grep when the ecosystem has intersearch embeddings and qmd, and when agentic/hybrid RAG is now table stakes (RAG-MCP, A-RAG). The fix is not a rewrite — it is wiring interlearn’s index.json into the shared embedding backend and adding the staleness-flagging the vision doc already mandates.

SOTA gap: Retrieval is flat keyword/grep — no semantic search, no embeddings, no agentic multi-hop retrieval. The 2025-26 frontier is agentic RAG and GraphRAG (A-RAG arXiv:2602.03442; GraphSearch arXiv:2509.22009): retrieval folded into the reasoning loop, hybrid dense+sparse, and graph-structured recall that beats flat vector/keyword for global/connected questions. The June-2026 finding that solution docs are precisely an episodic+semantic+procedural agent-memory corpus (Mem0/Zep/A-MEM; Anatomy of Agentic Memory arXiv:2602.19320) and the self-improvement/distillation loop (EvolveR arXiv:2510.16079 — distill trajectories into a retrievable library of named principles) means interlearn should be the consolidation+retrieval tier of an agent-memory subsystem, not a static grep index. It also lacks the staleness-detection its own vision doc calls for (no provenance-weighted decay or superseded-pattern flagging).

Redundancy: Notable overlap. (1) intersearch IS the ecosystem’s shared embedding+search infra (embedding_index/embedding_query) — interlearn reinvents flat search instead of routing through it. (2) interknow/qmd already provides local markdown search over 2946 docs (BM25 now, embeddings planned via qmd embed) and interknow is explicitly a ‘durable pattern repo with provenance’ — solution docs are exactly that corpus; the two should share a retrieval backend. (3) interphase does phase/gate validation for Beads, overlapping interlearn’s /audit (closed-bead reflect-coverage check). (4) clavain’s /compound + engineering-docs skill writes the very docs/solutions/*.md files interlearn indexes — they are producer/consumer and should share the frontmatter schema contract.

Actions:

Fix the hardcoded-path bug: replace literal /root/projects/Interverse in SKILL.md (and the /home/mk/projects/Demarch references in AGENTS.md/CLAUDE.md test commands) with ${CLAUDE_PLUGIN_ROOT}-relative or walk-up monorepo detection so the skill works on this machine’s /Users/sma/projects/Sylveste/interverse path — currently the /search and /index commands invoke a path that does not exist.
Route retrieval through shared infra instead of grep: feed index.json into intersearch’s embedding_index and back /search with embedding_query (hybrid dense+sparse), or delegate to interknow/qmd which already indexes these docs — eliminating the duplicated flat-search implementation and getting semantic recall for free.
Implement the staleness detection the vision doc already specifies: add a provenance/decay signal (age, last-touched module, superseded-by links) so /search can flag or down-rank stale solutions rather than silently serving them; cite the ‘episodic+semantic+procedural memory with consolidation policies’ frontier (Anatomy of Agentic Memory).
De-duplicate the audit boundary with interphase: either have /audit consume interphase’s gate-validation output or narrow interlearn’s audit to pure doc-coverage, and formalize a shared solution-doc frontmatter schema contract with clavain’s /compound + engineering-docs (the producers) so indexing stops fighting schema heterogeneity at parse time.