@oomkapwn/enquire-mcp 3.8.0-rc.13 → 3.8.0-rc.15

package/CHANGELOG.md

@@ -2,6 +2,164 @@
 
 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.0-rc.15] — 2026-05-24
+
+> **TL;DR:** Fifteenth v3.8.0 release candidate. **M-3 root-class fix — meta-recursion overclaim instance #10**: rc.14 added 7 new `docs-consistency.test.ts` invariants for the M-2 fix, but NONE had NEGATIVE control siblings — violating the CLAUDE.md rule since v3.6.4 ("every invariant test must have a sibling test that fails when the invariant is violated"). Same class as v3.7.14 F1+F2 (added a fix that itself shipped the same drift inside the same patch). Refactored 7 M-2 checks into pure functions, added 7 NEGATIVE control sibling tests (positive-negative pairs). Plus L-5 snapshot header on the audit-request doc. **862 tests** (+7 NEGATIVE controls vs rc.14). Ships under `@rc` dist-tag.
+
+**Minor — fifteenth v3.8.0 release candidate.**
+
+### Fix M-3 (MEDIUM) — meta-recursion: rc.14 invariants lacked NEGATIVE controls
+
+**Background.** CLAUDE.md anti-pattern since v3.6.4:
+> "Invariant test without negative-control — a test that ALWAYS passes proves nothing. Every new invariant test must have a sibling test that fails when the invariant is violated."
+
+rc.14 fixed M-2 by adding 7 invariants to `tests/docs-consistency.test.ts` covering llms.txt + AGENTS.md numeric claims. But all 7 used inline regex matching against real files — if the regex pattern had a typo (`/(\d) tests/` instead of `/(\d+) tests/`), the test would trivially pass on any input with at least one digit. No negative control = no proof the invariant actually detects drift.
+
+This is the **10th documented overclaim instance** in the cascade, and the 2nd "meta-recursion" instance: a methodology rule violation inside the very patch that implemented that rule's class fix. Same shape as v3.7.14 F1 (renameNote ordering fix shipped with stale TSDoc) → v3.7.14 F2 (renameFile ordering fix in same patch ALSO shipped with stale TSDoc — overclaim #6 followed by #7).
+
+**Fix** (`tests/docs-consistency.test.ts`): refactored each of the 7 M-2 checks into a pure function returning `null` on OK or an error string on drift:
+- `checkLlmsTestCount(llms, actual)` — "N unit tests" matches actual count
+- `checkLlmsToolBreakdown(llms, total, alwaysOn, optIn, writes)` — "N tools (A always-on + B opt-in + C writes)" matches all 4
+- `checkLlmsPromptCount(llms, actual)` — "N MCP prompts" matches
+- `checkLlmsCiGates(llms, required)` — "N required + M advisory CI gates" matches
+- `checkAgentsTestFloor(agents, actual)` — "X+ tests" is valid lower bound (claimed ≤ actual, gap < 50)
+- `checkAgentsPerFileFloors(agents, actualFloors)` — "N per-file branch floors" matches
+- `checkAgentsCiGates(agents, required)` — every "N required gates" mention matches
+
+Then 7 NEGATIVE control `it()` blocks call each function with intentionally-drifted inline fixtures:
+- Wrong count → assert non-null error matching the count
+- Missing claim → assert non-null error matching "must declare"
+- Matching claim → assert null (sanity)
+- Multi-field breakdowns: drift in each individual field → assert non-null with that field name in error
+
+Pattern matches `tests/peek-meta.test.ts` and `tests/k1-class-invariant.test.ts` (the canonical "extract pure function + fixture-based negative" template per v3.7.3).
+
+**Verification.** The negative tests caught one real logic bug in my own assertions during development (I had written `expect(checkAgentsTestFloor("800+ tests", 855)).toBeNull()` for a case that should actually fail because 855-800=55 exceeds the 50pp threshold). The NEGATIVE controls do their job: they pin the contract of the checker function itself, not just the file content.
+
+### Fix L-5 (LOW) — snapshot header on audit-request doc
+
+**Background.** `docs/audits/AUDIT-REQUEST-v3.8.0-2026-05-24.md` (created in rc.14 ship) contains numeric claims ("855 tests, 14 release candidates, 44 tools, 19 prompts") with no explicit indication these are a point-in-time snapshot. An auditor reading the doc after rc.16 or rc.17 ships would see stale-looking numbers and potentially question the documentation's reliability.
+
+**Fix.** Added a snapshot callout at the top of the doc:
+
+> 📌 Snapshot notice. This document is a snapshot from commit `bad0518` / `v3.8.0-rc.14` / 2026-05-24. Numeric figures cited below reflect the project state on that date. Later release candidates will increment some of these numbers; the auditor should target the commit SHA cited here (or the closest later release-candidate tag) for the actual review.
+
+The file's name already datestamps it (`AUDIT-REQUEST-v3.8.0-2026-05-24.md`), but the callout makes the snapshot semantics explicit in the rendered view.
+
+### Method note — documented overclaim instances
+
+Updated CLAUDE.md status section: overclaim count goes 9 → 10 with this rc.15 finding. Pattern of recurrence:
+- #1: v3.6.1 CRIT-1 — claimed 10 of 10 callsites fixed, was 1 of 10
+- #2: v3.6.2 K-1 — claimed all 10 callsites, was 4 of 10
+- #4: v3.7.11 D4 — claimed examples/ added in v3.7.10, actually v3.7.11
+- #6: v3.7.14 F1 — renameNote impl fixed but TSDoc lied
+- #7: v3.7.14 F2 — renameFile fix in same patch as #6 ALSO shipped TSDoc drift
+- #8: v3.7.14 — orphan-tag procedural error
+- #9: v3.7.14 F5 — release.yml permission-incomplete (HTTP 403)
+- **#10: v3.8.0-rc.14 M-2** — 7 invariants without negative-control siblings (this fix)
+
+The recursion-pair shape (#6+#7 in v3.7.14; #2 inside the "K-1 final" patch; #10 inside the rc.14 M-2 patch) keeps appearing. Documented in CHANGELOG so the next external auditor sees the methodology IS aware of this failure mode and treating it explicitly.
+
+### Stats
+
+- **862 tests** (+7 NEGATIVE control siblings for rc.14 M-2 invariants).
+- `tests/docs-consistency.test.ts`: 7 inline-regex invariants → 7 pure-function checks + 7 NEGATIVE controls.
+- All 5 surfaces re-bumped: README (×3), package.json, COMPARISON.md, llms.txt, AGENTS.md (855→862).
+- `npm audit`: 0 vulnerabilities.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally.
+
+### v3.8.0 remaining backlog
+
+- **External audit** before `@latest` promotion (CLAUDE.md rule since v3.6.1).
+- **Tier C** (deferred): JSON-LD `SoftwareApplication` schema on GH Pages, GitHub Sponsors funding.yml.
+- **T-2, T-3** — communities handler + hyde E2E.
+- **T-4** — optional serve-http HTTP smoke.
+- **Multi-subcommand CLI drift audit** (from rc.11 RCA).
+- OCR'd PDF watcher embed-sync, HNSW in-memory watcher update.
+
+---
+
+## [3.8.0-rc.14] — 2026-05-24
+
+> **TL;DR:** Fourteenth v3.8.0 release candidate. **Post-rc.13 audit closure** — 4 findings: M-2 (root-class fix: new files `llms.txt` + `AGENTS.md` introduced drift surface without invariant coverage), L-2 (`CLAUDE.md` status section stale at rc.12 — same α-class drift the methodology keeps fighting), L-3 (Tier B0 MCP Registry submission successfully completed but not documented in CHANGELOG), L-4 (PR #117 `server.json` schema validation fix had no CHANGELOG entry). 7 new docs-consistency invariants extend coverage to llms.txt + AGENTS.md numeric claims (test count, tool breakdown, MCP prompt count, CI gate count, per-file floor count). **855 tests** (+7 invariants vs rc.13). Ships under `@rc` dist-tag.
+
+**Minor — fourteenth v3.8.0 release candidate.**
+
+### Fix M-2 (MEDIUM) — root-class fix for new-file drift-surface gap
+
+**Background.** rc.12 added `llms.txt` (https://llmstxt.org/ standard for AI agents) and `AGENTS.md` (Cursor 2.0 / Claude Code / Codex coding-agent convention). Both contain numeric/structural claims — "848 unit tests", "44 tools", "19 MCP prompts", "9 required CI gates", "10 per-file branch floors" — that were NOT covered by the existing `docs-consistency.test.ts` invariants. Existing invariants checked README, STABILITY.md, COMPARISON.md, package.json description, and docs/api.md, but new files were a fresh drift surface.
+
+Post-rc.13 audit found this as a class-level methodology gap: **whenever we add a new docs surface with numeric claims, we must extend docs-consistency at the same time**, otherwise the surface will silently drift. Same class as M-1 (CLI help text drift before rc.11 lifted to `cli-help.ts`) — but for a *new* surface we created in rc.12 rather than a pre-existing one.
+
+**Fix** (`tests/docs-consistency.test.ts`): added a new `describe` block "llms.txt + AGENTS.md numeric claims (v3.8.0-rc.14 M-2)" with 7 invariants:
+1. `llms.txt` test count = actual `it()` count across `tests/*.test.ts`
+2. `llms.txt` tool breakdown `N tools (A always-on read + B opt-in + C gated writes)` = TOOL_MANIFEST counts per kind
+3. `llms.txt` MCP prompt count = `registerPrompt` count in `src/prompts.ts`
+4. `llms.txt` `N required + M advisory CI gates` count = `REQUIRED="..."` regex entries in `.github/workflows/release.yml`
+5. `AGENTS.md` `X+ tests` lower-bound assertion (≤ actual, with drift detection if actual >50 above floor)
+6. `AGENTS.md` per-file branch floor count = entries in `scripts/check-per-file-coverage.mjs` FLOORS object
+7. `AGENTS.md` `N required CI gates` (multiple mentions) all = `release.yml` REQUIRED count
+
+Tested empirically: invariants caught 7 fresh drift instances (test count now 855, not 848 — the 7 new invariants themselves changed the count). All surfaces updated to 855 in same commit.
+
+**Defense-in-depth.** This now means EVERY new docs surface in this repo must either (a) avoid numeric claims, OR (b) be added to docs-consistency invariants at the same time. CLAUDE.md anti-patterns updated with new rule.
+
+### Fix L-2 (LOW) — CLAUDE.md status section was stale at rc.12
+
+**Background.** CLAUDE.md line 119 said `**v3.8.0-rc.12 shipped (current)**` after rc.13 was already shipped + MCP Registry submission successful. Classic α-class drift the methodology specifically warns against.
+
+**Fix** (`CLAUDE.md`): updated status section to reflect rc.12 (shipped), rc.13 (shipped, includes MCP Registry submission confirmation), rc.14 (current). Same edit pattern as previous status updates.
+
+### Fix L-3 (LOW) — MCP Registry submission was not documented in CHANGELOG
+
+**Background.** rc.13 CHANGELOG entry predicted "After this RC publishes to npm, `mcp-publisher publish` submits server.json to the canonical MCP Registry." — but the *actual* successful submission was never recorded in any CHANGELOG entry. Audit trail gap.
+
+**Confirmation.** Successfully published to `https://registry.modelcontextprotocol.io` on 2026-05-24 09:18:29 UTC:
+- Server name: `io.github.oomkapwn/enquire-mcp`
+- Version: `3.8.0-rc.13`
+- Status: `active`
+- `isLatest`: `true`
+
+Live verification: `curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=enquire"` → 1 listing. Glama.ai, mcp.so, smithery.ai will auto-sync from this canonical source over 24-48 hours.
+
+Also opened **awesome-mcp-servers PR #6838** at `https://github.com/punkpeye/awesome-mcp-servers/pull/6838` in the Knowledge & Memory category. Awaiting maintainer review.
+
+### Fix L-4 (LOW) — PR #117 server.json validation fix was not documented
+
+**Background.** rc.13 shipped with `server.json` that failed MCP Registry validation (description >100 chars, runtimeArguments missing required `valueHint`/`value`/`name` fields per the v2025-12-11 schema). Fixed during the registry submission session and merged via PR #117 — but no CHANGELOG entry was added.
+
+**Confirmation.** PR #117 merged to main at commit ea3a4cc. Changes:
+1. `server.json` description: 489 chars → 91 chars (matches MCP Registry `length ≤ 100` constraint)
+2. PositionalArgument: added `valueHint: "subcommand"`, `value: "serve"`, ordered fields per schema
+3. NamedArgument: explicit `type: "named"` + `name: "--vault"` fields
+
+`mcp-publisher validate` now passes cleanly. The corrected `server.json` is what was published to the registry; this RC documents the gap.
+
+### Stats
+
+- **855 tests** (+7 docs-consistency invariants vs rc.13).
+- 2 surfaces newly covered by invariants: `llms.txt`, `AGENTS.md`.
+- 5 surfaces with test-count bumps: README (×3), package.json, COMPARISON.md, llms.txt, AGENTS.md.
+- `npm audit`: 0 vulnerabilities.
+- Dist-tag: `@rc` (v3.7.20 stays `@latest`).
+- All 9 required CI gates pass locally.
+
+### Method note
+
+**New rule (CLAUDE.md anti-patterns):** whenever a PR adds a new docs surface with numeric claims, the SAME PR must extend `docs-consistency.test.ts` to cover those claims. Otherwise the new surface becomes a fresh drift surface that the next external audit will catch. This generalizes the v3.7.17 OIA rule from "state-driven walks for existing files" to "structural invariants for new files".
+
+### v3.8.0 remaining backlog
+
+- **External audit** before `@latest` promotion (CLAUDE.md rule since v3.6.1 — required ≥2 independent external auditors per major).
+- **Tier C** (deferred): JSON-LD `SoftwareApplication` schema on GH Pages, GitHub Sponsors funding.yml.
+- **T-2, T-3** — communities handler + hyde E2E.
+- **T-4** — optional serve-http HTTP smoke.
+- **Multi-subcommand CLI drift audit** (from rc.11 RCA): install-model/build-embeddings/eval/bench for --include-pdfs/--embed-file/--json/etc.
+- OCR'd PDF watcher embed-sync, HNSW in-memory watcher update.
+
+---
+
 ## [3.8.0-rc.13] — 2026-05-24
 
 > **TL;DR:** Thirteenth v3.8.0 release candidate. **AI/LLM discoverability Tier B** — adds `mcpName` field to `package.json` (`io.github.oomkapwn/enquire-mcp`) and ships `server.json` at repo root, both required by the official MCP Registry verification (registry.modelcontextprotocol.io). Adds `CITATION.cff` for academic discoverability (Google Scholar / Semantic Scholar) citing the underlying research papers (HyDE, RRF, BM25, Louvain, HNSW, BGE). After this RC ships to npm, mcp-publisher can submit to the canonical MCP Registry — which auto-propagates to glama.ai, mcp.so, smithery.ai, and other downstream registries. **No code changes; metadata + documentation only.** 848 tests unchanged. Ships under `@rc` dist-tag.

package/README.md

@@ -13,7 +13,7 @@
 [![CI](https://github.com/oomkapwn/enquire-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/oomkapwn/enquire-mcp/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@oomkapwn/enquire-mcp.svg?label=npm&color=cb3837)](https://www.npmjs.com/package/@oomkapwn/enquire-mcp)
 [![downloads](https://img.shields.io/npm/dm/@oomkapwn/enquire-mcp.svg?color=cb3837)](https://www.npmjs.com/package/@oomkapwn/enquire-mcp)
-[![tests](https://img.shields.io/badge/tests-848%20passing-brightgreen.svg)](#trust)
+[![tests](https://img.shields.io/badge/tests-862%20passing-brightgreen.svg)](#trust)
 [![stable](https://img.shields.io/badge/v3.7.x-stable-brightgreen.svg)](./STABILITY.md)
 [![SLSA-3](https://img.shields.io/badge/SLSA-3-blue.svg)](https://slsa.dev/spec/v1.0/levels#build-l3)
 [![MCP](https://img.shields.io/badge/MCP-1.29-8A2BE2.svg)](https://modelcontextprotocol.io/)
@@ -38,7 +38,7 @@ Your Obsidian vault becomes **persistent, queryable long-term memory** for any M
 > 2. **Best-in-class retrieval.** Hybrid BM25 + multilingual embeddings + BGE cross-encoder reranker fused via RRF, scaled with HNSW + int8 quantization. The same IR stack a search startup would build — open-sourced, in one binary.
 > 3. **Zero cloud calls during serve.** Models cached locally (one-time download from HuggingFace). Your vault content never leaves your machine. Air-gap-safe by default.
 
-**44 tools · 19 MCP prompts · 848 unit tests · 50+ languages · v3.7.x stable · semver-bound · MIT · SLSA-3 signed.**
+**44 tools · 19 MCP prompts · 862 unit tests · 50+ languages · v3.7.x stable · semver-bound · MIT · SLSA-3 signed.**
 
 ---
 
@@ -176,7 +176,7 @@ Auto-generated **[API reference at oomkapwn.github.io/enquire-mcp](https://oomka
 | **GraphRAG-light** (wikilink community detection via Louvain modularity) | ✅ **only here** | ❌ | ❌ |
 | **Standalone `.base` query execution** (works without Obsidian running) | ✅ **only here** | ❌ | ❌ delegates to Obsidian |
 | **HyDE retrieval** (Gao et al 2023) + sub-question decomposition | ✅ **only here** | ❌ | ❌ |
-| **848 unit tests · 9 required + 4 advisory CI gates per PR** | ✅ | n/a | rare |
+| **862 unit tests · 9 required + 4 advisory CI gates per PR** | ✅ | n/a | rare |
 | **SLSA-3 build provenance** | ✅ | n/a | ❌ |
 | **Semver-bound public surface** ([STABILITY.md](./STABILITY.md)) | ✅ | n/a | ❌ |
 | Standalone (no Obsidian plugin needed) | ✅ | ❌ requires Obsidian | varies |
@@ -286,7 +286,7 @@ Channel: `npm install @oomkapwn/enquire-mcp` → latest stable. Full changelog:
 ```bash
 git clone https://github.com/oomkapwn/enquire-mcp.git
 cd enquire-mcp && npm install
-npm test       # full suite (848 tests, ~5s)
+npm test       # full suite (862 tests, ~5s)
 npm run lint   # zero warnings
 npm run build  # tsc → dist/
 ```

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.0-rc.13";
+export declare const VERSION = "3.8.0-rc.15";
 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.0-rc.13";
+export const VERSION = "3.8.0-rc.15";
 // 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

@@ -43,7 +43,7 @@ The four axes the external audit (#3, 2026-05) called out as decisive — **REST
 | Read open editor state, active note, etc.     | **No**              | **Yes**          | Limited          | No               | No               |
 | Zero outbound network calls in serve mode     | **Yes** (default)   | Local-only (REST)| Local-only (REST)| Yes              | Yes              |
 | SLSA-3 build provenance on releases           | **Yes**             | No               | No               | No               | No               |
-| Test count (public)                           | **848**             | (varies)         | (varies)         | (varies)         | (varies)         |
+| Test count (public)                           | **862**             | (varies)         | (varies)         | (varies)         | (varies)         |
 | Tool count                                    | 44                  | ~25              | ~8               | ~10              | 3–5              |
 | MCP prompt count                              | 19                  | 0                | 0                | 0                | 0                |
 | License                                       | MIT                 | Apache-2.0       | MIT              | MIT              | (varies)         |

package/package.json

@@ -1,9 +1,9 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@oomkapwn/enquire-mcp",
-  "version": "3.8.0-rc.13",
+  "version": "3.8.0-rc.15",
   "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, 848 tests, SLSA-3, semver-bound, MIT, zero cloud calls during serve.",
+  "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, 862 tests, SLSA-3, semver-bound, MIT, zero cloud calls during serve.",
   "type": "module",
   "bin": {
     "enquire-mcp": "dist/index.js"