walk

/walk

Intent. Walk the graph and return what's relevant. Semantic search is the default; topology operations are opt-in via flags.

Modes

Semantic mode (default)

User asks: /walk how does annealing relate to crystallisation in dmsn synthesis?

1. Route to qmd MCP. Use lex (BM25) + vec (semantic) sub-queries. Pass intent so qmd's snippets are useful.
2. Optionally augment with hyde (hypothetical document) if the query is abstract.
3. Score and merge results. Filter by minScore: 0.5 to drop low-confidence hits.
4. Return a ranked list:

   [[claim-title-1]] (claim, confidence: probable)
     description...
     why-it-matched: ...
   [[claim-title-2]] ...
   

Topology mode

Specific operations on the graph structure. Each is a flag; tools/topology.py provides the computation.

Flag	What it returns
--orphans	claims with no inbound or outbound [[wikilinks]]
--bridges <topic>	claims with high betweenness centrality bridging the named topic to others
--neighbors <claim> [--depth N]	claims within N hops of the named claim
--centrality	ranked list of high-centrality (hub) claims
--moc-coverage	list of claims that aren't in any _<topic>.md MOC
--disconnected-clusters [--min-size N]	pairs of MOCs that share no member claims and no 1-hop cross-edges. Meta-MOCs (frontmatter meta: true) are excluded so they don't pollute the lonely-pair signal.

Mixed mode

A semantic query with a topology constraint, e.g. /walk crystallisation --neighbors-of dmsn-synthesis --depth 2. Run topology to get a candidate set, then semantic-rank within it.

Behaviour

1. Parse the argument: query string, flags.
2. Read vault/vault.yaml. Check qmd.enabled, surrender.enabled, surrender.walk_integration. Re-read every invocation; never cache any flag.
3. If topology flag → invoke tools/topology.py with the appropriate sub-command. Parse result.
4. If semantic and qmd.enabled: true → invoke qmd searches. Parse + filter. Continue at step 6.
5. If semantic and qmd.enabled: false → use the grep-fallback path (see "Grep fallback" section below). Continue at step 6.
6. If topology + semantic → constrain semantic to topology-result subset.
7. Format the output as a ranked list with descriptions and a short why-it-matched annotation.
8. If surrender.enabled && surrender.walk_integration: read engagement frontmatter from each result claim, compute decay, render the engagement column and the weakest-grip panel. Else: skip surrender rendering entirely; output is byte-identical to the gated-off behaviour.
9. Print, with a one-line preamble noting which retrieval path was used (qmd / grep-fallback) and the surrender state (enabled / off).