Skip to content

GH-30: debug runmode — doctor subcommand and live diagnostics - #33

Merged
blainemotsinger merged 33 commits into
mainfrom
GH-30
Sep 29, 2026
Merged

GH-30: debug runmode — doctor subcommand and live diagnostics#33
blainemotsinger merged 33 commits into
mainfrom
GH-30

Conversation

@blainemotsinger

@blainemotsinger blainemotsinger commented Sep 29, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Summary

Adds a debug runmode for knowledge-mcp (design + plan: ./tmp/docs/ session docs):

  • knowledge-mcp debug — one-shot startup diagnosis reusing the real startup path (projects.BuildWithStore → search.Location → lazy index open). Three report sections (Resolution, Startup trail with a watchdog-bounded index self-query, Environment) followed by ok/warn/fail findings; exit 1 iff any fail. Distinct fail index.locked vs fail index.open; --no-index-on-startup blocked queries warn instead of fail; zero-entry stores are healthy/fresh.
  • Live diagnostics — --debug / --log-file <path> (implies --debug) log startup phases and tool calls to stderr with sanitized arguments (entry bodies never written; sizes only). ok= derives from both err and res.IsError.
  • Hook diagnostics — KNM_DEBUG=1 enables the same logging for the Grep/Glob hook-augment plugin hook.
  • Shared startup path — index-location logic moved to search.Location (character-identical move + tests) so the doctor cannot drift from server behavior.
  • Docs + indexer — README ### Debugging section, knowledge-file example corrected to the project:/version:/entries: wrapper form; knowledge.Load failures now warn (missing optional category files stay silent).

Default behavior is unchanged (no flags ⇒ no new output); no new dependencies.

Test plan

  • go build ./... / gofmt -l . / go vet ./... clean
  • go test ./... — 9/9 packages (includes warm-index race regression under -race)
  • KNM_BIN=./knowledge-mcp prove evals/t/ — 175/175
  • make eval-mock — 18/18
  • Manual smoke: knowledge-mcp debug --root ... renders three sections, exit 0; KNM_DEBUG=1 hook-augment logs hook.skip

Task-scoped reviews passed for all 6 plan tasks plus fix rounds; final whole-branch review (b63a5f9..a55ede2) passed after one fix round (7ed72ae).

closes #30

@blainemotsinger
GH-30: add eval scenario schema and loader
62badd8
@blainemotsinger
GH-30: add eval deterministic assertion core
b12fbb4
@blainemotsinger
GH-30: fix forbidden_new_paths allow matching and fail closed
14aa6db
@blainemotsinger
GH-30: add eval mock tier and eval-mock target
0e2c33f
@blainemotsinger
GH-30: fix duplicate git_rev_count rows in RunMock
2943925
@blainemotsinger
GH-30: add eval sandbox builder
2510f6f
@blainemotsinger
GH-30: add eval real-tier runner core
677c529
@blainemotsinger
GH-30: fix MCP tool name normalization in runner evidence
c3e5cf2
@blainemotsinger
GH-30: seed pilot store fixture and flip query_knowledge assert
b5858b7
@blainemotsinger
GH-30: raise pilot timeout and sync mock test fixture
acf28ca
@blainemotsinger
GH-30: lift provider block by model prefix
20fdf3c
@blainemotsinger
GH-30: make eval model pin configurable
dd17e22
@blainemotsinger
GH-30: utf8-encode sandbox file writes
5efbe9d
@blainemotsinger
GH-30: pin provider-lift failure message and flag fallthrough
3924e5b
@blainemotsinger
GH-30: add eval judge and make eval target
665d8bc
@blainemotsinger
GH-30: harden judge spawn against arg limits and orphaned children
b3a28a7
@blainemotsinger
GH-30: add wave 1 gate eval scenarios
18f8e31
@blainemotsinger
GH-30: tighten gate asserts and wire mock verification
fbf30ed
@blainemotsinger
GH-30: add wave 2 convention eval scenarios
51d80eb
@blainemotsinger
GH-30: add wave 3 soft eval scenarios and CI workflow
47d9236
@blainemotsinger
GH-30: document behavior eval targets
bf204c7
@blainemotsinger
GH-30: fix review findings in eval corpus and judge clip
b63a5f9
@blainemotsinger
GH-30: add diag logger and arg sanitizer
edf33ae
@blainemotsinger
GH-30: add tool-call debug logging and server debug flags
81a6d12
@blainemotsinger
GH-30: fix tool.done ok flag to honor result errors
c0821c4
@blainemotsinger
GH-30: add hook debug logging via KNM_DEBUG
1bec123
@blainemotsinger
GH-30: move index location logic into search package
0812fa4
@blainemotsinger
GH-30: add debug doctor subcommand
421f13e
@blainemotsinger
GH-30: fix doctor stale flag, close race, and lazy index open
58b44af
@blainemotsinger
GH-30: fix doctor warm-index kick ordering and close race
fe7c65d
@blainemotsinger
blainemotsinger merged commit 0f1a76a into main Sep 29, 2026
2 checks passed
@blainemotsinger
blainemotsinger deleted the GH-30 branch September 29, 2026 01:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

add corpus tests

1 participant

@blainemotsinger