Skip to content

feat(health): expose fsck as kb.fsck on mcp/jsonl/capabilities - #739

Open
philluiz2323 wants to merge 2 commits into
vouchdev:testfrom
philluiz2323:feat/kb-fsck-expose
Open

feat(health): expose fsck as kb.fsck on mcp/jsonl/capabilities#739
philluiz2323 wants to merge 2 commits into
vouchdev:testfrom
philluiz2323:feat/kb-fsck-expose

Conversation

@philluiz2323

Copy link
Copy Markdown
Contributor

What changed

health.fsck() is now registered on MCP (kb_fsck), JSONL (kb.fsck),
and capabilities.METHODS, mirroring kb_doctor's registration exactly.
The CLI mirror (vouch fsck) already existed and needed no change — it
already matches the default kb.foovouch foo naming rule
test_cli_commands_match_methods checks against.

Why

health.fsck() (orphaned embeddings, dangling supersede/contradict
chains, decided-proposal ↔ artifact mismatches, index-vs-file drift) was
called from exactly one place: cli.py's fsck command. kb.lint and
kb.doctor both have full four-surface registration; fsck — the
deepest of the three checks — was the one gap, leaving an agent no way
to run it without shelling out to the CLI.

Closes #738

What might break

Nothing — purely additive. health.fsck() itself is completely untouched;
this only wires its existing, unmodified output to three more surfaces
the same way kb.doctor already does.

Heads up for review: while testing this I confirmed health.fsck() on
current test HEAD still crashes with an uncaught KeyError on any
approved DELETE (and separately, GOAL) proposal — the bug my own
#735 (still open) fixes. That crash is pre-existing and orthogonal to
this PR (it lives entirely inside _check_decided_proposals, which this
PR never touches) — but worth flagging that exposing kb.fsck here makes
that crash reachable from MCP/JSONL agents too, not just CLI users of
vouch fsck. I'd suggest merging #735 around the same time as this one
if convenient, though neither PR strictly depends on the other.

VEP

Not applicable — no object model, on-disk layout, bundle format, or
audit-log shape change. A registration-only change wiring an existing,
unmodified function to three more surfaces.

Tests

  • Local make check-equivalent: ruff clean (src + tests); mypy
    clean; tests/test_health.py, tests/test_capabilities.py,
    tests/test_hot_memory.py, tests/test_cli.py all pass
  • New behaviour has tests — 3 new cases in tests/test_health.py:
    JSONL kb.fsck result matches a direct health.fsck() call,
    findings round-trip through the JSONL envelope (not just the ok
    flag), and a pin confirming kb.fsck's default CLI-mirror name
    correctly resolves to the pre-existing fsck command with no
    _CLI_MIRRORS entry needed
  • CHANGELOG.md updated under ## [Unreleased]

health.fsck() (orphaned embeddings, dangling supersede/contradict
chains, decided-proposal <-> artifact mismatches, index-vs-file drift)
was called from exactly one place, cli.py's fsck command. kb.lint and
kb.doctor already have full mcp/jsonl/capabilities registration -
fsck was the one gap in that otherwise-complete trio, leaving an agent
no way to run the deepest check without shelling out to the CLI.

register kb_fsck on mcp and _h_fsck on jsonl, mirroring kb_doctor's
registration exactly, plus the capabilities.METHODS entry and
hot_memory.py's coverage registry (excluded with the same reason
kb.lint/kb.doctor already carry: diagnostics, no claim payload). the
CLI mirror needed no change - vouch fsck already exists and matches
the default kb.foo -> vouch foo naming rule test_cli_commands_match_
methods checks against.

Closes vouchdev#738
@github-actions github-actions Bot added docs documentation, specs, examples, and repo guidance mcp mcp, jsonl, and http surfaces retrieval context, search, synthesis, and evaluation tests tests and fixtures size: S 50-199 changed non-doc lines labels Jul 31, 2026
diff-coverage flagged server.py:1204-1205 (kb_fsck's report = health.
fsck(_store()) / return {...}) as untested - the existing jsonl-level
test exercises _h_fsck, never the mcp wrapper function itself.

add a direct call matching the pattern newer kb.* methods already use
(test_explain_ranking.py's test_mcp_surface_serves_explain_ranking):
monkeypatch server._store to the test fixture, call server.kb_fsck()
directly, and diff its result against a direct health.fsck() call.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs documentation, specs, examples, and repo guidance mcp mcp, jsonl, and http surfaces retrieval context, search, synthesis, and evaluation size: S 50-199 changed non-doc lines tests tests and fixtures

Projects

None yet

Development

Successfully merging this pull request may close these issues.

expose health.fsck() as kb.fsck on MCP/JSONL/capabilities (roadmap 1.5)

1 participant