Fix search ranking and --hop, make the evidence rule and CI gates actually check something

[debuggerone]

Started from three bugs in the Go search and ended up in the evidence model,
because each fix uncovered a gate that could not fail.

Search (bin/kbsearch)

• FTS ranked backwards. QUERY_FTS_INDEX used ORDER BY score where
  kblib has always used ORDER BY score DESC, so the Go search took the
  worst BM25 matches and fed them into RRF in reverse rank order.
• Nil dereference. SET STREAM_SANDBOX ran on the package-level conn
  before OpenConnection; any run with KBTEST_EPS set panicked.
• --root returned nothing. Results were truncated to -n before the
  root/repo filters, so every matching leaf below the cut was discarded —
  --root facts came back empty whenever info leafs filled the top N. The
  deduction order was unreachable from the CLI.
• The daemon was never started. ensureDaemon() existed and was never
  called, so every query loaded the ~100MB potion matrix in-process — the
  thing the daemon exists to avoid. It now auto-starts in its own session,
  with KBSEARCH_NO_DAEMON=1 to opt out.

--hop existed only in the docs

Documented in six files, implemented in none, and it failed silently: the
parser dropped unrecognised -flags but kept their arguments, so the
documented example bin/kb/search "what runs on arc-2" --hop 1 searched for
"what runs on arc-2 1".

Implementing it surfaced the reason nobody noticed: the graph had no
edges. init_schema declared FROM_FILE, HAS_VERSION and RUNS_ON,
kblib advertised "Cypher graph hops", and a fresh index produced 47 Leaf
nodes, 0 File nodes and 0 edges. kb/index and mail/index_mail now write
File nodes and FROM_FILE edges (47 leafs → 12 files → 47 edges), and
--hop N walks them, tagging results with the depth they were reached at.
Unknown flags are now an error instead of being absorbed into the query.

The evidence rule was never checked

facts/audit db verified that " x " appeared in Leaf.source. That is a
claim about a string, not about evidence — "bullshit x bullshit2" passed
it. And the string was all there was: the schema flattened the sources into
one free-text field.

• A source is now structured (kind, method, locator, origin) and two
  sources count as independent only when kind and origin both differ.
  Two compose files are two paths but one kind of claim — corroboration, not
  independence. Every source needs a locator, because evidence you cannot go
  back and look at is not evidence.
• Evidence is stored as (Evidence)-[:SUPPORTS]->(Leaf), shared rather than
  copied, so "how many independent things did we actually look at" stays
  answerable. audit db counts observations, kinds and origins; the source
  string is no longer consulted by any check.
• facts/crm used to record loc="bin/facts/crm" — the tool answering
  "where did you see it" with its own path. It now points at the CRM export
  key and the yaml org id.

Verified by injecting two forged facts into a real database: both are
caught, the blunt one (evidence=0) and the subtle one (two compose files,
2 evidence nodes and 2 origins but kinds=['declared']).

CI gates were fail-open

./bin/facts/audit self 2>/dev/null || echo "audit: not yet implemented; gate skipped"
./bin/kb/eval 2>/dev/null || echo "eval: not yet implemented; gate skipped"

kb/eval had in fact never run: the step used the system python instead
of uv run, died on import ladybug, and the || branch reported it as
"not yet implemented". Even with uv it would have failed — nothing built an
index and var/ is gitignored. Its control set also asked about "DevOps",
which appears nowhere in the repo corpus, pinning recall at 0.667.

Both gates now run through uv run with no || and no 2>/dev/null, an
index is built first (HF model from actions/cache, ~1GB cold), and the
control questions are ones the repo corpus can answer.

audit self was three greps

It checked that PLAN.md contained "recall@5" and that README mentioned
HNSW/BM25 — with 2.source as a regex, unescaped dot. It could not go red.
It now runs the pairing rule against a fixture, checks the tool convention
(D14), and verifies that every bin/… shown in a doc code block exists
and accepts the flags it is shown with. That last check is what would have
caught --hop; the narrower version I wrote first did not.

Findings it produced, all fixed here: bin/md/tables and bin/brain/deduce
advertised in AGENTS.md do not exist, skills/diataxis-docs documented a
--type filter and --hop following related: links that were never
implemented, and bin/md/import had no usage block.

One decision left to the maintainer

skills/agent-cost documents bin/agents/cost, which was never vendored
into this repo (PLAN D2). Rather than delete a skill, it is declared in
EXTERNAL_TOOLS with a reason and printed under exceptions on every
audit self run:

exceptions:
  - "bin/agents/cost: skills/agent-cost documents the upstream tool; not
     vendored into this repo (PLAN D2). Vendor it or drop the skill."

An invisible suppression is how --hop survived in six files. Vendor the
tool or drop the skill — either way the exception should go.

Verification, and its limits

Green: 96 python tests, audit self and audit db clean, recall@5 1.0
after a rebuild from an empty var/, go vet + go test ./... on the root
module.

Not verified, stated plainly:

• bin/kbsearch was never compiled. It needs the native ladybug library
  (lib-ladybug/, gitignored) which was not available. I built stub modules
  for the two cgo dependencies and ran go vet and the package tests over
  every real source file — that is how an unused strings import left by
  this change was caught — but the Cypher in hopStmt has never executed.
  Its python counterpart kblib.neighbours_of is tested against a real
  database.
• bin/facts/crm was never run: neither /tmp/opencode/crm/graph.json
  nor the knowledge-mesh yaml exists outside its own environment. Reviewed
  and syntax-checked only.
• The nested bin/kbsearch module is still outside CI for the same reason,
  recorded as OQ5. OQ6 records that Evidence.value_hash is written
  empty and nothing re-runs a locator, so confirmed still means "was true
  when observed" and staleness cannot be detected.

Happy to split this into separate PRs (search / evidence model / CI+audit)
if that reviews better — the commits are already grouped that way.

🤖 Generated with Claude Code

[debuggerone]

The one finding this PR does not fix — skills/agent-cost documenting bin/agents/cost — is filed separately as #3, since dropping a skill is a maintainer's call. This PR only declares it as a visible exception in the meantime.

[eSlider]

Verdict: request changes

This PR found that several gates were theatre and replaced them with checks that can actually go red. The FTS ascending-score bug, filter-before-limit, unknown flags being swallowed into the query, and " x " in source were all real. The tests name the failure mode. OQ5/OQ6 are written as open questions instead of papered over. That is the right standard for this repo.

Blocking before merge (AGENTS.md + PLAN D8/D15):

1. No absolute /mnt/ paths in committed files or in persisted evidence. bin/facts/crm now interpolates /mnt/8TB/... and /tmp/opencode/... into Evidence locators/origins.
2. File identity is path-only. Two repos with README.md share one File node; --hop then walks across repos.
3. The ranking/parser tests do not run in CI. rank.go/args.go sit in the cgo module. The thesis of this PR is that a gate must be able to fail — these tests need a cgo-free package so go test on ubuntu-latest actually runs them.
4. --hop drops --root/--repo and treats a DB error as exit 0. Same class of silent failure this PR exists to kill.
5. bin/facts/audit module docstring still describes the " x " source check the rest of the PR removed (rule 6: docs reflect behaviour).

Also:

• Drop the "Generated with Claude Code" footer from the PR body. Commits carry Co-Authored-By: Claude Opus 5; squash-merge can drop those trailers. This repo does not attribute PRs/commits to AI.
• CI has not reported on this fork PR yet. First-time contributor workflows often need maintainer approval — please trigger the Checks tab after addressing the above.

Happy to re-review a follow-up that keeps the evidence model and the fail-closed CI. The commit grouping (search / evidence / CI+audit) is already the right split if this needs to land in pieces.

[eSlider]

Blocking — GitHub safety (AGENTS.md rule 1) and PII.

CORPUS_MESH is still /mnt/8TB/projects/eslider/cv/.... This change now writes that absolute path (and /tmp/opencode/crm/graph.json) into Evidence.locator / Evidence.origin, so a later audit db dump or leaf export leaks a host path into the graph.

The old loc="bin/facts/crm" was the wrong kind of pointer; this is the right kind with the wrong value.

• Resolve both inputs from env ($PROJECTS_ROOT, $HOME, or a gitignored config path). Do not commit /mnt/, /home/<user>/, /Users/<user>/.
• Store locators as repo-relative / logical keys (knowledge-mesh-seed.yaml:orgs:<id>, oo-crm:companies_with_persons:<key>), not host paths.
• The fact text still interpolates CRM person names into root=facts on a public repo. That was pre-existing, but this path now persists it as structured evidence — keep third-party names out of committed fixtures and prefer ids over names in leaf text.

Also: json.load(open(CRM_GRAPH)) is still an unclosed handle.

[eSlider]

Blocking — File identity ignores repo.

fid = sha256_b64(path)[:24] hashes the path only. repo is stored as a property and then overwritten on MERGE.

The brain indexes multiple corpora (repo markdown, mail, ops). Two README.mds (or the same relative path in mail vs tree) collapse onto one File node. --hop then returns siblings from the other repo — the walk this PR just made real.

Include repo in the id (sha256(f"{repo}:{path}")), and do not MERGE-overwrite f.repo.

Secondary: mtime here is the observation clock from upsert_leaf, not the file's mtime. That will make D10/HAS_VERSION staleness lie. Pass the real mtime (or leave it unset until git/import owns it).

[eSlider]

audit db does not enforce locators, unlike make_fact.

check_independence refuses an empty locator. This gate only counts nodes / distinct kinds / distinct origins. A writer that bypasses make_fact (or upsert_evidence(..., locator="")) can store two kind+origin pairs with nowhere to re-check, and audit db stays green.

The PR's own rule: evidence you cannot go back and look at is not evidence. Count locators here too (and reject empty kind/origin rather than dropping them from the set).

Thank you for killing " x " in source — the injected bullshit x bullshit2 case is exactly the test this needed.

[eSlider]

Docs reflect behaviour (AGENTS.md rule 6).

This docstring still says db asserts a two-source source (the " x " pairing). The function below deliberately stopped doing that — that was the point of the PR.

Readers of the tool file will re-learn the bug you just removed. Update this block to: Evidence nodes, ≥2 observations, ≥2 kinds, ≥2 origins, locator present.

[eSlider]

Same class of silent failure this PR exists to kill.

1. Hop DB errors are printed to stderr, then results = walked and runSearch returns 0. The user gets a successful YAML document with no hop key and no non-zero exit. Unknown flags now fail closed (good); this path is still fail-open.
2. rankAndFilter honours --root/--repo, then expandHops appends every sibling of the file, including the other root. bin/kb/search "q" --root facts --hop 1 will mix info leafs back in. Deduction is facts first; the filter has to apply to hopped hits too (or be documented as intentionally unfiltered, with a test).

hopStmt itself is fine as a mirror of kblib.neighbours_of (tested in Python). The Go []any bind has never executed — if ladybug rejects the param type, this branch will hit (1) on every --hop. Return non-zero.

[eSlider]

Thank you. This is the test the old hybrid+truncate+filter sequence could not have passed. The comment states the failure mode in one sentence. Same for TestParseHopIsNotSwallowedIntoTheQuery and the RRF tie-break.

Please get these onto CI (cgo-free package — comment on ci.yml). A perfect regression test that never runs is how --hop survived in six docs.

[eSlider]

Thank you. Unknown flags as an error with exit 2 is the correct fix for "documented --hop 1 searched for query 1". Validating --root / -n / --hop instead of silently keeping the default is the same standard.

[eSlider]

Thank you. This is the actual D8 rule: kind and origin, locator required, taxonomy closed, make_fact refuses instead of rendering a string that looks like two sources.

The pairing helpers staying pure (no docker, no db) is why audit self can run in CI. The "two compose files are corroboration" refusal is the one that would have been impossible to express with " x " in source.

[eSlider]

Thank you. Unguarded FTS is the right default: a missing index must fail the gate, not report recall 0.0. Control questions that the repo corpus can actually answer were the other half of this fix.

[eSlider]

Thank you for actually calling ensureDaemon and for Setsid so Ctrl+C on the search does not kill the server.

Please also Release() the child after Start (otherwise the CLI holds a zombie until it exits), and serialise the bind: two concurrent searches can both miss /health and both spawn serve on 17830. First wins, second dies after 10s and falls through to a 100MB in-process load — which is the path this change was meant to avoid.

[eSlider]

Rebase required — current main has moved

The review above was on the PR diff. Checking against current main (fe6a020) changes the merge decision.

This branch is based on 1d1f6a9 and does not contain:

• b73b4d4 — fix(kb): stop DROP INDEX killing HNSW via Ladybug ghost catalog
• ff1716d / 98c14e2 — absolute /mnt/ paths removed; bin/facts/crm already uses KNOWLEDGE_MESH_SEED / repo-relative fallback

So a merge as-is would regress two landed fixes:

1. kblib.create_fts_and_vector / drop_indexes in this PR still DROP INDEX IF EXISTS Leaf.Leaf_*. On Ladybug 0.19 that leaves ghost catalog entries (_0_Leaf_vec_UPPER, 0_id_docs); CREATE then fails while SHOW_INDEXES omits the index. Current main made drop_indexes a no-op and forbids DROP. Keep that. Evidence/link_to_file/neighbours_of must land on top of current kblib.py, not replace it.
2. bin/facts/crm here hardcodes /mnt/8TB/projects/eslider/cv/... and then writes that path into Evidence locators. Current main already dropped that constant. Rebase and keep the env-var path; locators must stay logical (knowledge-mesh-seed.yaml:orgs:<id>), not host paths.

Please rebase onto current main and re-run the python tests + audit self. The Go search fixes (FTS DESC, filter-before-limit, OpenConnection before SET, actually calling ensureDaemon) are still missing on main and are still wanted — they just cannot ship with the old kblib DROP path.

Do not mix with unrelated local WIP (LinkedIn chats / models/ weights).