@oomkapwn/enquire-mcp 3.8.1 → 3.8.3

package/CHANGELOG.md

@@ -2,6 +2,144 @@
 
 All notable changes to this project will be documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.3] — 2026-05-24
+
+> **TL;DR:** **OIA Check 7 — extend stale-currency-claim detection from `src/*.ts` to `docs/*.md` + `CLAUDE.md`.** Closes the methodology gap exposed by v3.8.2: state-driven sweep found 6 stale-version refs in docs that OIA Check 1 had been silently skipping because it only walked `src/`. Same recursion meta-class as M-1 (lift only some flags to cli-help.ts) and M-2 (extend invariants only to some docs surfaces). Generalized: Check 7 walks `docs/*.md` + `CLAUDE.md`, matches present-tense currency-claim patterns ("stable v3.X.x", "@latest ships v3.X.x", "accurate as of v3.X.Y", "exact for v3.X.x", "covers the v3.X.x"), compares against `package.json` current major.minor, fails on mismatch (unless explicit history context: "initial", "from", "since", "Pre-", "added", "fix", etc.). `docs/audits/` excluded (historical snapshots by definition). Bonus: removed stale Cursor audit ref in `scripts/oia-walk.mjs` header comment (v3.8.1 retraction missed it). **No code changes; 872 tests unchanged.**
+
+**Patch — structural defense expansion.**
+
+### Background
+
+v3.8.2 state-driven audit found 6 stale-version references across `CLAUDE.md` + `docs/api.md` + `docs/COMPARISON.md`. The lesson noted in v3.8.2 CHANGELOG:
+> The current OIA walk does NOT scan docs/ for version-string staleness. Backlog item: extend OIA Check 1 to walk docs/*.md and CLAUDE.md looking for "v3.X.Y" references that mention current state.
+
+v3.8.3 ships that backlog item.
+
+### What Check 7 does
+
+For each file in `CLAUDE.md` + `docs/*.md` (excluding `docs/audits/`):
+1. Read line by line.
+2. For each line, try 5 currency-claim patterns:
+   - `stable v(\d+\.\d+)\.x` — "stable v3.X.x" stability claims
+   - `(@latest|ships) v(\d+\.\d+)\.x` — npm @latest claims
+   - `covers the v(\d+\.\d+)\.x` — scope claims
+   - `exact for v(\d+\.\d+)\.x` — exactness claims
+   - `accurate as of v(\d+\.\d+\.\d+)` — accuracy timestamp claims
+3. If matched version's major.minor ≠ current major.minor, AND no history-context marker in surrounding 3 lines (`initial`, `from`, `since`, `Pre-`, `was`, `added`, `fix`, `bumped`, etc.), record `STALE-DOC-CURRENCY-CLAIM` finding.
+
+### Empirical validation
+
+- On main HEAD (post v3.8.2 docs refresh): **0 findings** ✓ (proves the fix worked).
+- On a synthetic test fixture with intentionally stale claims: all 4 patterns fire correctly, history-context detection correctly skips legitimate tombstones.
+- Initial pre-refinement run on `docs/audits/` flagged 4 historical audit-report quotes — root-caused as legitimate (those files are by-definition snapshots) and excluded via path filter.
+
+### Why this is the right shape for the recursion class
+
+The methodology pattern is:
+1. Find a class of bug (e.g. drift)
+2. Build a structural defense (e.g. cli-help.ts, OIA Check N)
+3. **Apply defense to ONE surface, leave siblings unprotected**
+4. Discover sibling surface drifts the next audit cycle
+5. Extend defense to the sibling surface
+
+Step 4 is the recurring failure. The defense is correct but its scope is too narrow. The fix shape is always "lift the defense to cover all siblings."
+
+Cf. M-1 lift to cli-help.ts (rc.11), M-2 extend docs-consistency to llms.txt + AGENTS.md (rc.14), M-REG-1 extend check-version-consistency to server.json (rc.18, retracted in v3.8.1 but kept technical fix). v3.8.3 Check 7 is the same shape applied to OIA Check 1.
+
+### Bonus fix — Cursor audit reference removal from oia-walk.mjs
+
+v3.8.1 retraction removed Cursor audit references from CHANGELOG + CLAUDE.md but missed the inline comment at `scripts/oia-walk.mjs:416`:
+> IMPORTANT (v3.8.0-rc.18 L-OIA-1, per Cursor external audit on rc.15)
+
+Updated to:
+> IMPORTANT (v3.8.0-rc.18 S-AUDIT-3, self-audit on rc.17)
+
+This is a small consequence of the v3.8.1 retraction (one stale ref slipped through the cleanup). Documented openly here.
+
+### Stats
+
+- **872 tests** (unchanged — script enhancement only).
+- `scripts/oia-walk.mjs`: 6 checks → 7 checks.
+- 0 code changes in `src/`.
+- `npm audit`: 0 vulnerabilities.
+- Dist-tag: `@latest = 3.8.3` after publish.
+- All 9 required CI gates pass locally.
+
+### What's next
+
+Backlog (no scope changes):
+- T-2/T-3/T-4 E2E tests
+- OCR'd PDF watcher embed-sync, HNSW in-memory live update
+- HTTP P2-10/P2-11 lifecycle hardening
+- Tier C discoverability
+- v3.9.0 architectural items (HNSW filter-during-search, embed-db migrations, distributed rate-limit)
+
+---
+
+## [3.8.2] — 2026-05-24
+
+> **TL;DR:** **State-driven audit findings — 6 stale-version fixes across CLAUDE.md + docs/api.md + docs/COMPARISON.md.** Post-v3.8.1 full self-audit (using OIA methodology applied broadly) found 6 stale-version references across documentation that survived the v3.6.0→v3.8.1 cascade: CLAUDE.md header still said "v3.7.x maintenance" (we're at v3.8.x stable), backlog status said "before promotion to v3.8.0 stable" (already promoted), docs/api.md said "stable v3.7.x @latest" (npm @latest = 3.8.1 → 3.8.2 with this patch), docs/COMPARISON.md timestamps still pinned to v3.7.0 (2026-05-15). All fixed in this docs-only patch. **No code changes; 872 tests unchanged.**
+
+**Patch — state-driven docs refresh.**
+
+### Background
+
+After v3.8.1 retraction shipped (overclaim #11), ran a full state-driven sweep of the repo to find other stale fragments. The methodology lesson from v3.7.17 OIA ("internal change-driven sweeps miss state-driven failure modes") was applied broadly: read every doc file as-it-is, verify each claim against current reality.
+
+The sweep found 6 findings, all stale-version drift:
+- **A-1 / A-2 / A-3** (MEDIUM): `CLAUDE.md` header and intro paragraph stuck at "v3.7.x maintenance + v3.8.0 architectural" framing. v3.8.0 already shipped + v3.8.1 retraction + v3.8.2 here means current state is "v3.8.x stable maintenance + v3.9.0 architectural deferrals."
+- **A-5** (LOW): `CLAUDE.md` v3.8.x backlog status said "External audit before promotion to v3.8.0 stable" — v3.8.0 already promoted (without audit, overclaim #11), so phrasing should be "External audit STILL OPEN per v3.6.1 (v3.8.0 promoted without it)."
+- **A-7** (MEDIUM): `docs/api.md:5` said "stable v3.7.x (@latest on npm)" — externally visible incorrect claim; npm @latest = 3.8.1 → 3.8.2.
+- **A-8** (LOW): `docs/COMPARISON.md` timestamps at v3.7.0 (intro, table footer, signature) — should reference v3.8.x stable.
+
+A-4 (MCP Registry version drift) is separately tracked as a manual action item (requires OAuth re-publish, scheduled for after this RC ships).
+
+### Fixes
+
+**`CLAUDE.md` header:**
+- "Project goal — v3.7.x maintenance + v3.8.0 architectural" → "v3.8.x stable maintenance + v3.9.0 architectural"
+- Intro paragraph rewritten to acknowledge v3.8.0 + v3.8.1 shipped, list what v3.8.0 minor delivered, what was deferred to v3.9.0+, and that external audit blocker remains OPEN.
+
+**`CLAUDE.md` backlog bullet:**
+- "Remaining v3.8.0 items: ... External audit before promotion to v3.8.0 stable" → "Remaining v3.8.x/v3.9.0 items: ... External audit blocker per v3.6.1 STILL OPEN — v3.8.0 was promoted without it (overclaim #11, retracted v3.8.1)."
+
+**`docs/api.md:5`:**
+- "stable v3.7.x (@latest on npm)" → "stable v3.8.x (@latest on npm)"
+- Removed v3.7.0 quality-batch reference; replaced with v3.8.0 minor highlights + v3.8.1 retraction note.
+
+**`docs/COMPARISON.md`** (4 sites):
+- Intro paragraph: "accurate as of v3.7.0 (2026-05-15)" → "accurate as of v3.8.x stable (initial 2026-05-15 for v3.7.0; refreshed in v3.8.2 docs patch)"
+- Table footer: "44-tool count is exact for v3.7.x" → "exact for v3.8.x stable"
+- Snapshot date: "snapshot as of 2026-05-15 (v3.7.0)" → "snapshot as of 2026-05-24 (v3.8.x stable; initial v3.7.0 from 2026-05-15)"
+- Signature: "— enquire-mcp maintainer, v3.7.0" → "— enquire-mcp maintainer, v3.8.x stable"
+
+### Why this is a class lesson (not just isolated drift)
+
+The v3.8.0 cascade (rc.1 → rc.18) had 18 chances to update these surfaces. None did. **Reason:** my change-driven sweeps only inspect files I'm actively editing in the current RC. Files I'm not touching get a "no drift detected" signal even when they're full of stale current-state claims.
+
+This is exactly the failure mode the v3.7.17 OIA walk was added to prevent — but OIA Check 1 (stale version tombstones in src/*.ts file headers) covers only `src/` files, not docs/. The current OIA walk does NOT scan docs/ for version-string staleness.
+
+**Backlog item (deferred to v3.8.3+):** extend OIA Check 1 to walk `docs/*.md` and `CLAUDE.md` looking for "v3.X.Y" references that mention current state ("stable v3.X.x", "as of v3.X.Y", "exact for v3.X.x") and compare against current major.minor. Tombstones (`vX.Y.Z added Z`, `vX.Y.Z fix W`) are legitimate history and should not flag. Distinguishing "current claim" from "historical tombstone" is the hard part — likely needs a comment-marker convention.
+
+Not blocking v3.8.2: this drift is now refreshed manually. The structural defense is a separate improvement.
+
+### Stats
+
+- **872 tests** (unchanged — pure docs patch).
+- 4 files touched: CLAUDE.md, docs/api.md, docs/COMPARISON.md, CHANGELOG.md (this entry).
+- 0 code changes.
+- `npm audit`: 0 vulnerabilities.
+- Dist-tag: `@latest = 3.8.2` after publish (v3.8.1 demoted automatically; users on @latest get 3.8.2).
+- All 9 required CI gates pass locally.
+
+### What's next
+
+- **MCP Registry re-publish** (was action item from A-4): bump registry from v3.8.0-rc.13 → v3.8.2 via `mcp-publisher publish`. Requires user OAuth approval (same flow as v3.8.0-rc.13 original publish).
+- **External audit outreach** — blocker per v3.6.1 still open, primary work item.
+- **Backlog**: T-2/T-3/T-4 E2E, OCR watcher embed-sync, HNSW live update, P2-X HTTP lifecycle, Tier C discoverability, OIA Check 1 extension to docs/.
+
+---
+
 ## [3.8.1] — 2026-05-24
 
 > **TL;DR:** **Retroactive correction patch (overclaim instance #11).** v3.8.0 STABLE (shipped earlier today) and v3.8.0-rc.18 both referenced a "Cursor external audit" with verdict 4.85/5 as the basis for `@rc → @latest` promotion. **That audit reference was incorrect** — the document was for a different project and was mistakenly applied to enquire-mcp. **The 3 technical fixes in rc.18 remain valid** (server.json version drift was real, terminal `vault.isExcluded` in `searchHybrid` is safe defense-in-depth, OIA workflow ordering doc is useful) — these would have been found by the next internal self-audit regardless. **What is retracted** is the audit attribution narrative and the "first external audit sign-off" claim in the v3.8.0 entry. v3.8.0 STABLE @latest stays on npm (no rollback — users who already installed shouldn't be disrupted, and the codebase quality is independently verifiable via 872 tests + 9 required CI gates + 89.91% coverage). External audit per CLAUDE.md v3.6.1 rule (≥2 independent auditors) is **still pending**; the v3.8.0 promotion was on internal confidence alone, which is documented honestly in this patch. **No code changes; documentation correction only.** 872 tests unchanged.

package/dist/index.d.ts

@@ -7,7 +7,7 @@
  * + `McpServer({version})`) and `src/tool-registry.ts` (used in the
  * `vault-info` resource payload).
  */
-export declare const VERSION = "3.8.1";
+export declare const VERSION = "3.8.3";
 export { main } from "./cli.js";
 export { buildEmbedText, buildMcpServer, formatReadyBanner, prepareServerDeps, type ServeOptions, type ServerDeps, startServer } from "./server.js";
 export { parsePositiveInt, parseQuantizationMode } from "./tool-registry.js";

package/dist/index.js

@@ -40,7 +40,7 @@ import { main } from "./cli.js";
  * + `McpServer({version})`) and `src/tool-registry.ts` (used in the
  * `vault-info` resource payload).
  */
-export const VERSION = "3.8.1";
+export const VERSION = "3.8.3";
 // Re-exports — preserve the v3.5.x public surface so http-transport.ts and
 // tests don't need to know about the new module layout. The set below
 // exactly matches the v3.5.x `export` declarations: `main`,

package/docs/COMPARISON.md

@@ -1,6 +1,6 @@
 # enquire-mcp vs. other Obsidian MCP servers
 
-**enquire-mcp positions itself as a long-term memory layer for AI agents, built on an Obsidian vault** — open-source, MCP-native, vendor-neutral, with the strongest retrieval stack in the open-source Obsidian-MCP space (BM25 + TF-IDF + ML embeddings, RRF-fused, BGE cross-encoder reranked, HNSW + int8 quantized). The alternatives below take different trade-offs — some are agent-first, some are Obsidian-plugin-first, some optimize for local-REST-API integration over hybrid retrieval. This document is a side-by-side feature matrix plus an honest "when to pick which" guide, written by the enquire-mcp maintainer. It is intentionally fair-not-sales: each alternative has scenarios where it is the better pick, and those scenarios are called out below. Numbers and feature claims for enquire-mcp are accurate as of v3.7.0 (2026-05-15); claims about the four alternatives are based on their public READMEs as of the same date — please verify against their current state before deciding.
+**enquire-mcp positions itself as a long-term memory layer for AI agents, built on an Obsidian vault** — open-source, MCP-native, vendor-neutral, with the strongest retrieval stack in the open-source Obsidian-MCP space (BM25 + TF-IDF + ML embeddings, RRF-fused, BGE cross-encoder reranked, HNSW + int8 quantized). The alternatives below take different trade-offs — some are agent-first, some are Obsidian-plugin-first, some optimize for local-REST-API integration over hybrid retrieval. This document is a side-by-side feature matrix plus an honest "when to pick which" guide, written by the enquire-mcp maintainer. It is intentionally fair-not-sales: each alternative has scenarios where it is the better pick, and those scenarios are called out below. Numbers and feature claims for enquire-mcp are accurate as of v3.8.x stable (initial snapshot 2026-05-15 for v3.7.0; refreshed to v3.8.x in v3.8.2 docs patch); claims about the four alternatives are based on their public READMEs as of the same dates — please verify against their current state before deciding.
 
 ## Servers compared
 
@@ -56,7 +56,7 @@ Notes on the matrix:
 
 - **"Limited" for markus on Obsidian-side operations:** it covers a smaller subset of REST endpoints than cyanheads.
 
-- **Tool counts for alternatives** are approximate from public READMEs and may have shifted. enquire-mcp's 44-tool count is exact for v3.7.x and is verified by `tests/docs-consistency.test.ts` against `src/tool-manifest.ts` (machine-readable single source of truth, introduced v3.6.0-rc.2).
+- **Tool counts for alternatives** are approximate from public READMEs and may have shifted. enquire-mcp's 44-tool count is exact for v3.8.x stable and is verified by `tests/docs-consistency.test.ts` against `src/tool-manifest.ts` (machine-readable single source of truth, introduced v3.6.0-rc.2).
 
 - **License row** is informational, not a recommendation. MIT and Apache-2.0 are both permissive; pick what your org's policy requires.
 
@@ -239,7 +239,7 @@ As of v3.6.0-rc.4, **enquire-mcp ships public, reproducible end-to-end retrieval
 
 ## Disclaimer
 
-This is a snapshot as of **2026-05-15** (v3.7.0). All five servers are actively developed (or in some cases archived) and the feature matrix will drift. Before making a decision:
+This is a snapshot as of **2026-05-24** (v3.8.x stable; initial v3.7.0 snapshot from 2026-05-15). All five servers are actively developed (or in some cases archived) and the feature matrix will drift. Before making a decision:
 
 1. Re-read each alternative's current `README.md` — features land between matrix updates.
 2. Run each candidate against a sample of your own vault for an hour. Retrieval quality, in particular, is vault-specific and unreliable to compare from feature lists alone.
@@ -247,4 +247,4 @@ This is a snapshot as of **2026-05-15** (v3.7.0). All five servers are actively
 
 Corrections to this document are welcome — open an issue or PR on [`oomkapwn/enquire-mcp`](https://github.com/oomkapwn/enquire-mcp). Specifically: if a row above understates an alternative's capabilities, that's a bug in this doc and we'd like to fix it.
 
-— enquire-mcp maintainer, v3.7.0
+— enquire-mcp maintainer, v3.8.x stable

package/docs/api.md

@@ -2,7 +2,7 @@
 
 **enquire is the most advanced Obsidian MCP — a long-term memory layer for AI agents, built on your Obsidian vault.** Open-source, MCP-native, vendor-neutral persistence: agents (Claude Code / Claude Desktop / Cursor / ChatGPT / Codex / OpenClaw / any MCP client) get durable, queryable recall across sessions, models, and providers — your knowledge lives in plain markdown you own, not a vendor cloud. 44 MCP tools (33 always-on read + 4 opt-in read + 7 opt-in write); the 4 opt-ins are: 1 via `--persistent-index` + `--diagnostic-search-tools` (`obsidian_full_text_search` — needs BOTH flags: persistent-index for the FTS5 index, diagnostic-search-tools to surface it as a single-ranker tool alongside the hybrid default `obsidian_search`) + 3 via `--diagnostic-search-tools` (the single-ranker `obsidian_search_text` / `obsidian_semantic_search` / `obsidian_embeddings_search` — gated by default in v2.0+ since `obsidian_search` auto-detects + fuses signals). 2 + 1 opt-in MCP resources, 19 MCP prompts. **v3.1.0+ adds `obsidian_hyde_search`** (HyDE-augmented retrieval, Gao et al 2023; agent supplies a synthetic answer, server embeds it for retrieval) plus the `vault_research` (sub-question decomposition) and `vault_synthesis_page` (Karpathy LLM-Wiki synthesis loop) prompts. v2.6.0+ also speaks Streamable HTTP via `serve-http` (bearer auth + rate-limit + CORS). v2.7.0+ indexes PDFs as a separate read tool surface; **v2.8.0+ blends PDF chunks into `obsidian_search` hybrid retrieval** with `--include-pdfs` — every hit carries a `kind: "md" | "pdf"` flag and PDF snippets include `[page: N]` markers for citation. **v2.9.0+ adds BGE cross-encoder reranking** on top of RRF with `--enable-reranker` — typical +5-10 NDCG@10 retrieval-quality boost. **v2.10.0+ adds Tesseract OCR for image-only / scanned PDFs** via `obsidian_ocr_pdf` — completes the PDF retrieval story.
 
-> **Channels:** stable v3.7.x (`@latest` on npm) ships 44 tools including `obsidian_search` (hybrid BM25 + TF-IDF + ML embeddings, RRF-fused) with optional BGE cross-encoder reranking, `obsidian_embeddings_search`, `obsidian_hyde_search`, plus the `install-model` / `build-embeddings` / `clear-embeddings` / `setup` / `doctor` / `eval` subcommands. The `@rc` dist-tag carries the most recent release candidate. Benchmarks live behind `npm run bench:retrieval` (not a CLI subcommand). This document covers the **v3.7.x stable** surface — see [CHANGELOG.md](../CHANGELOG.md) for the v3.7.0 quality batch that closed the post-v3.6.4 audit cycle (K-1 class structurally enforced at 4 levels, ~20× faster search hot path via peek caching, per-file branch coverage floors, GitHub repo metadata invariant).
+> **Channels:** stable v3.8.x (`@latest` on npm) ships 44 tools including `obsidian_search` (hybrid BM25 + TF-IDF + ML embeddings, RRF-fused) with optional BGE cross-encoder reranking, `obsidian_embeddings_search`, `obsidian_hyde_search`, plus the `install-model` / `build-embeddings` / `clear-embeddings` / `setup` / `doctor` / `eval` subcommands. The `@rc` dist-tag carries the most recent release candidate. Benchmarks live behind `npm run bench:retrieval` (not a CLI subcommand). This document covers the **v3.8.x stable** surface — see [CHANGELOG.md](../CHANGELOG.md) for the v3.8.0 minor (K-3 readOnlyHint invariant, R-7 watcher embed-db sync, Tier A/B AI/LLM discoverability, 8 new structural invariants) and v3.8.1 retraction (overclaim instance #11 — incorrectly-attributed external audit).
 
 > Versioned dynamically — see [`CHANGELOG.md`](../CHANGELOG.md) for the current release.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@oomkapwn/enquire-mcp",
-  "version": "3.8.1",
+  "version": "3.8.3",
   "mcpName": "io.github.oomkapwn/enquire-mcp",
   "description": "MCP server giving AI agents (Claude Code, Claude Desktop, Cursor, ChatGPT, Codex, OpenClaw) persistent long-term memory backed by your local Obsidian markdown vault. Hybrid retrieval (BM25 + ML embeddings + BGE reranker, RRF-fused), HNSW + int8 quantization, agentic RAG (HyDE + sub-question decomposition), GraphRAG-light (Louvain), standalone Obsidian Bases, PDFs + Tesseract OCR. Vendor-neutral memory layer for any MCP-compatible agent. 44 tools, 19 MCP prompts, 872 tests, SLSA-3, semver-bound, MIT, zero cloud calls during serve.",
   "type": "module",