ragmark: Instructions file for Claude Code

ragmark — Agent Operating Rules

ragmark is local-first retrieval over markdown / [[wikilink]] vaults — hybrid (vector + lexical) chunk search, a documented note-level similarity view, wikilink-aware context expansion, and a first-party MCP surface. Embeddings run locally (fastembed); the package makes no network egress at query time. Sibling of graphmark, which it consumes for deterministic graph reads.

This file governs autonomous (afk) work in this repo. It is the contract.

Non-negotiables

• The quality oracle is the golden-query set, and it is executor-untouchable. The golden data file is hand-curated by the owner (it lives vault-side, never in this repo — vault note content never ships). You may run it (ragmark golden), you may never generate, edit, or "fix" golden data. It grows only by a human adding the reproducing query for a found defect. There is deliberately NO parity oracle against the predecessor (improve-during-cutover, the-vault#143) — this harness and the invariants below are the only safety mechanism.
• Safety invariants are permanent. No silent embedding truncation (total embedded chars == total chunkable chars — the predecessor silently dropped 27.8%); every indexed note retrievable; chunk↔vector conservation; context gating never leaks. Assertions bind at rank/set level with the model pinned via the index manifest — never at vector bytes.
• The gating suite is teeth-checked, in CI. scripts/teeth_check.py re-runs the gating-marked tests with the filter defanged and requires red. A gating test that stays green with the filter off is a build failure. Never weaken a gating test to make teeth pass.
• Implement within the seeded interfaces. model.py, config.py, gate.py's boundary, and the module seams define the shape; the MCP face (names, args, annotations) is a decided contract (the-vault#142) pinned by tests/test_mcp_face.py. Do not redesign boundaries or rename their types. Exception: an issue that explicitly directs a seeded-surface change (a human-triaged decision, recorded in the issue) wins — follow the issue.
• Owed-behavior xfails are conductor-owned. tests/test_contract.py marks unimplemented seams with strict xfails. When your slice implements one, the xfail XPASSes and fails the suite — the same PR must replace it with real behavior tests (pre-frozen by the conductor where the slice plan says so).
• TDD, always. Failing test first, watch it fail, minimum to pass, refactor. Small, single-purpose PRs. Conventional commits; stage explicitly.
• Human merge gate. Nothing merges without human review.