Repository navigation
Unify knowledge drift health and connect and upgrade existing Wiki entities - #266
Merged
theyashasvipandey merged 24 commits intoOct 8, 2026
Conversation
Add a layout-insensitive token hash (semicolons, trailing commas and quote style set aside) and a body-only variant that parses a method inside a class wrapper. grounding-evidence keeps a checkout-local, content-addressed cache of grounded bodies (.mex/local/grounded-bodies/<bodyHash>.txt), re-hashed on every read, and answers whether a changed body differs only in comments or only in layout. The Wiki grounding snapshot exposes it and loads the grammars first.
The Wiki/Hub health resolver now asks the graph to explain a body that no longer matches its committed hash. Only comments changed (the committed codeHash, now carried by the index as code_hash, or the remembered old body) or only layout changed resolves fresh with a drift note instead of changed, so the Wiki agrees with mex check. A rebound (moved or renamed) symbol whose fingerprint differs gets the same explanation. Index schema 4.
…arby A fact names concrete tokens (identifiers, calls, private names, literals, numbers). When the remembered old body and the current body differ only in lines that name none of them - each change widened to its enclosing list, call or object literal and two lines of context - and every named token still occurs as often as before, the grounding resolves fresh with a changed-nearby note. Every doubt (no anchors, no old body, large body) keeps changed. Tests cover the layout hash, body evidence over real files, the resolver rows and the fact-aware rule.
Entities matching the same terms in the broader tier used to tie and fall back to title order. Ties now go to the entity whose text is most about the matched terms (title weighted as the tier weights it), in both the CLI and Hub search.
…ndency Entity health stays the worst of its groundings; instead of binding groundings to sentences inside a coarse entity, setup population and GROW now write each specific code-linked claim as its own section entity (a create-entry operation through mex wiki apply) grounded to every symbol whose change could make it false, naming the identifiers and literals it depends on. Doc and config prose stays grouped. This reuses the existing entity, index and query model unchanged, so every consumer (query, for-code, Hub) gets per-claim health without a new per-sentence binding format.
Facts about a property (its default value, private vs #) could not be grounded because property and field nodes had no body hash, so no fingerprint. Add them to the body kinds and bump the tree-sitter extractor version so existing graphs re-extract.
A grounded hit whose health was never resolved (index built without a code graph) or is unverified (graph unavailable or stale) reads as unflagged. wiki query now adds an info notice, WIKI_HEALTH_UNCHECKED, counting those groundings and pointing at mex graph plus wiki rebuild-index.
wiki rebuild-index resolves health inside withFreshGroundingPublication, which never loaded the tree-sitter grammars, so every comment and layout hash was null and comment-only or formatting-only edits stayed changed. Load them on both snapshot paths, with a port test over a real edit.
Checked against the knowledge benchmark's answer key at its final checkpoint: anchoring a fact to the symbol's own declaration line (cookie parse()) or to a single token (index.ts exports, grounded to the class) let a false fact resolve changed-nearby. Anchors now ignore file paths and conventional receivers (app., c.), only count below the declaration line, and a fact needs at least two of them before a change can be called nearby.
mex setup --cli --tool claude --yes no longer waits on a terminal: the AI tool comes from --tool (repeatable, none for no tool) and is saved like a menu choice, population counts as finished once the scaffold has no placeholders left, and the optional closing prompts are skipped. For scripts, CI and benchmarks.
The Hub sorted some-terms hits by score then title, so the bm25 tie-break only reached the CLI. Carry the relevance through and test both surfaces.
`mex check` and the Wiki each had their own code for "did this linked code change?", and they disagreed (comment-only edits, renames, layout). Now `check` resolves every link through `resolveGrounding`, the function the Wiki index uses, and names the result with one shared verdict: fresh, changed-nearby, moved, changed, missing, ambiguous or unverified. - Links are read through the Wiki codec, so `mex:` maps, `<!-- mex:entity -->` blocks and a root `grounds_to` are all seen, each link once, and every finding carries its entity id and title. - A rename is judged by structure: an unchanged body under a new name is `moved` (an unscored GROUNDING_MOVED notice), not GROUNDING_DRIFT. - Layout-only edits join comment-only ones, and a change away from everything the fact names is an unscored GROUNDING_NEARBY_DRIFT notice. - A link with no committed body hash is no longer judged from the graph.db cache; it reports GROUNDING_NO_BASELINE, since structure cannot see an edited constant. - Old bodies are also recalled from `_mex_grounded_source` by hash, for both paths alike. The new agreement test grounds a Wiki entity to real code, makes seven edits, and asserts both paths name the same, correct verdict.
The index resolved each grounding with the entity's text, but the Hub's live re-resolution passed neither the fact nor the committed code hash, so a change away from the fact, or one only in comments, could read `changed` in the Hub while the index and `mex check` said fresh. Every view now resolves exactly as the index does. The agreement test also asserts the health `wiki rebuild-index` stores for each edit.
`wiki validate` resolved every grounding itself (missing, unresolved, stale, no body hash), a third place deciding whether linked code changed. Those findings now come only from `mex check`, which uses the shared verdict and attaches the entity. Validate keeps the Wiki's structure: ids, types, relations, evidence, inline anchors and generated views. It no longer opens the code graph, so the graph-availability fields and the "grounding checks did not run" notice are gone.
The "still true" answer to a flagged entity needs a safe write that never asks anyone to copy a hash. `mex wiki reground <entity-id>` resolves each link with the shared verdict, follows a moved symbol to its new node, and hands the result to the ordinary `set-grounding` operation, which re-derives the node id, fingerprint and body hash from the live graph. It plans by default and writes only with --apply, bound to the entity's revision and content hash. A missing or ambiguous link refuses the whole request and writes nothing, so the flag stays for a person to resolve.
`check` now reports Wiki entities whose links changed, and those findings flow into the one interactive sync session beside scaffold drift. The brief lists each flagged entity with its id, title and link verdicts, and asks the agent to compare the fact with the recorded and current code and decide: still true (run `mex wiki reground --apply`), changed (fix the text, then reground), or unsure (leave the flag). Missing and ambiguous links are repaired by hand or left flagged; the agent never writes a hash. After the session sync rebuilds the Wiki index from a fresh graph and stops with a non-zero exit if that fails, then re-checks as before and names every reviewed entity that is still flagged. Still interactive only. Tests drive sync with a fake agent.
The Knowledge views already show the shared verdict. A record whose links are changed, missing or ambiguous now says so in its header and names the two commands that act on it: `mex check` lists the links and `mex sync` reviews the record. The Hub's own actions stay maintenance (graph and Wiki index refresh and rebuild).
README, the sync template and the help text for check, sync, wiki validate and wiki for-code now say the same thing: `mex check` runs every deterministic check, Wiki code links included, with the verdict the Wiki shows; `mex sync` fixes and reviews in one interactive session; `wiki query` and `wiki for-code` find the knowledge.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Unify code-grounding health across
mex check, Wiki reads/indexes, and live Hub views. Formatting, comment-only edits, unchanged moves, and changes away from the identifiers/literals a fact names are reported consistently; missing, ambiguous, and behavior-changing links remain actionable.wiki regroundafter verification.wiki link-sectionsto preview/apply supported section-to-parent relationships through the existing atomic operation batch. Keep authored parents visible in the bounded Hub graph.wiki upgradefor reviewing existing coarse knowledge without rerunning setup. It uses sync's agent chooser, optional tool override, manual prompt fallback, fresh-graph/drift guards, and resumable bounded batches.Why
Knowledge health previously depended on which surface read it, and splitting claims left section entities disconnected from their context. This gives existing and new projects a consistent, reviewable knowledge workflow while preserving read-only browsing and explicit writes.
Type of change
How to test
Run
npm run typecheckandnpm run build(the complete build includes Hub assets).Run the focused Wiki/sync tests:
On a grounded project with a fresh graph, compare check and Wiki/Hub health after formatting, comment, rename, nearby, and behavior edits. Confirm informational notices are not stale flags.
Preview
mex wiki link-sections, then apply explicitly. Verify claim text, ids, grounding baselines, existing relationships, and valid graph endpoints are preserved.Preview
mex wiki upgrade. Confirm it writes nothing. Explicit review uses the same agent chooser as sync; missing CLI support yields a copyable prompt, and unavailable graphs or flagged candidate groundings prevent agent launch.Open Hub and verify repeated diagnostics expand to the original entries and the graph retains linked parents within its existing output limits.
Validation: 59 focused Wiki/sync tests and the earlier 8 focused Hub diagnostic tests passed; type checks, the full build, and diff checks passed. Read-only upgrade previews were checked on five existing projects. The full test suites and required CI checks now pass on Node 22.22.0 and Node 24; no real agent-led fact migration is claimed.
Checklist
npm test)Behavior changes:
wiki validatenow checks structure; usemex checkfor code grounding. A link without a recorded body hash reportsGROUNDING_NO_BASELINErather than silently using a cached baseline. Moves and changed-nearby outcomes are informational. New repair/upgrade commands preview by default; opening Hub and installing an update never rewrite knowledge automatically. Package-root exports are unchanged.Code-graph changes
mainLanguageExtractororFrameworkResolverinterfacecore / discuss-firstissue is linked aboveNo new grammar, language mapping, extractor, or resolver is introduced. This includes code-body normalization, class-property fingerprinting, and grounding drift-semantics changes. No linked scope/discussion issue is claimed; the corresponding items remain unchecked.