feat(ghost): rank closest nodes in gather + ERR_UNKNOWN_SURFACE grounding#197
Draft
nahiyankhan wants to merge 2 commits into
Draft
feat(ghost): rank closest nodes in gather + ERR_UNKNOWN_SURFACE grounding#197nahiyankhan wants to merge 2 commits into
nahiyankhan wants to merge 2 commits into
Conversation
Add a ranked, cross-domain over nodes, surfaces, and checks: verbatim matches first, a whole-name typo fallback, then multi-word token coverage so a natural phrase like 'payment confirmation screen' still finds the right surface. Each hit carries its follow-up command. Emit the stable ERR_UNKNOWN_SURFACE code with closest-id suggestions when gather, checks, or review is given a surface absent from the package, instead of silently empty-routing. Add a provenance-based self-check skill recipe that probes grounding (what you gathered, Ghost-backed vs provisional, where it is silent) rather than presuming composition facets exist.
Collapse the standalone `ghost search` command into `gather`: an inexact `gather <query>` now ranks the closest nodes as candidates instead of dumping the whole menu, the same act as picking from the menu done intelligently. This drops a command in keeping with the project's one-road values, retains `searchGraph` as the ranking engine (node-only now; the weak check-keyword domain is removed since checks are routed by surface, not searched), and keeps `closestIds` feeding ERR_UNKNOWN_SURFACE suggestions on checks/review.
nahiyankhan
changed the title
This was referenced Jun 29, 2026
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.
Stacked on
ghost/07-directory-tree.Borrows two agent-grounding ideas from Meta's Astryx design system, adapted to Ghost's prose-node-graph model and to the project's "one road" values. I verified Astryx's actual behaviour against its live MCP
searchendpoint rather than its docs — its "fuzzy for typos" claim does not hold (butonreturns nothing) — so this does not copy that, and adds proper multi-word handling instead.What's here
Ranked node matching, folded into
gatherRather than adding a standalone
searchcommand (Astryx's shape, which suits a 150-component library), the ranking is folded intogather— the act is the same as picking from the node menu, done intelligently:ghost gather(no arg) → full node menughost gather <exact-id>→ compose the sliceghost gather <inexact-query>→ ranked candidates instead of dumping the whole menuRanking is deterministic and LLM-free: verbatim match (exact id > name > description > body), then a whole-name typo fallback, then multi-word token coverage so a natural phrase like
payment confirmationfinds the right surface.searchGraphstays as the reusable ranking engine inghost-core.ERR_UNKNOWN_SURFACEA node/surface absent from the package is an error, not a silent empty result.
gatherreturns ranked candidates under this code;checksandreviewemit it with closest-id suggestions. One stable code — not a broad ERR_* taxonomy.Self-check skill recipe
A pre-generation probe that tests grounding/provenance (what you gathered, Ghost-backed vs provisional, where the fingerprint is silent) rather than presuming composition facets exist — so it holds for any fingerprint regardless of author, product, or maturity. Composition prompts are optional and treat silence as a valid answer.
Design notes
searchcommand. It overlappedgather's existing "no-arg lists the menu to match against" behaviour, and the cross-domain story was weak: checks are routed by surface, not keyword-searched. Folding it keeps the CLI at 9 commands.--dense.--format jsonalready serves the machine path; Ghost's payload is authored prose we don't want to mechanically compress.closestIdsis the shared fuzzy seam between gather's ranking and the surface guard.Verification
pnpm test(113 passing, +search unit tests, +gather candidate CLI tests)pnpm checkgreen (biome, typecheck, file-size, terminology, install-bundle, cli-manifest in sync)minorchangeset added.