okf-query

name	okf-query
description	Multi-hop query and subgraph extraction over OKF bundles for progressive disclosure. Use when packing minimal context for long-running agents, exploring the neighborhood of a concept, or answering what relates to X within N hops.

OKF Query & Progressive Disclosure

Goal

Answer graph questions and emit minimal context packs (subgraphs) instead of dumping entire directories.

This is the read-path optimizer. Defaults exist so a long-running agent does not eat the whole second brain.

Query types

Intent	Approach
Neighbors of X	1-hop inbound + outbound
Context pack for agent run	2-hop outbound subgraph around the entry concept
Path A → B	BFS / path search on typed edges
By type	Filter concepts where frontmatter type matches
By tag	Filter on tags
Trust slice	Prefer verified: true and non-stale nodes

Process

1. Resolve bundle root and query target(s).
2. Prefer deterministic tools:
   • okf graph, search, or list commands if available
   • Fallback (defaults: 2 hops, 20 nodes, outbound-only):

     python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" pack <bundle> <concept> --hops 2 --max-nodes 20
     python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" subgraph <bundle> <concept> --hops 2
     python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" backlinks <bundle> <concept>
     python3 "${CLAUDE_PLUGIN_ROOT}/scripts/okf-graph.py" edges <bundle> --rel depends_on
     

3. Shape results for the consumer:
   • Human / agent pack: use pack → markdown field (preferred)
   • JSON: nodes + typed edges for downstream steps
4. Cap pack size. Default hops = 2, max-nodes = 20. Increase only if the user needs deeper context.
5. Annotate trust: mark unverified or draft nodes so consumers can deprioritize them. Do not silently omit schema-declared high-impact unverified nodes — flag them.

Deep reference: references/progressive-disclosure.md.

Progressive disclosure pack format

# Context pack: <root concept>
Hops: 2 | Nodes: N | Generated: <timestamp>

## Entry
- path, type, one-line description

## Included concepts (read order)
1. ...
2. ...

## Graph (Mermaid)
```mermaid
graph LR
  A --> B

Excluded (available on request)

• siblings / deeper hops summary

## Rules

- Outbound-only by default. `--undirected` floods through Catalog hubs; prefer `impact` for “what would break?”.
- Prefer verified, active nodes when trimming packs under a size budget.
- Do not silently omit high-impact unverified nodes — flag them (`x-impact` from the owning plugin).
- Absolute paths in links inside packs so agents can open files reliably.
- Never fabricate nodes missing from the bundle.

## Done when

- Query answered with explicit hop depth and node count
- Pack is small enough for agent context (or user approved a larger extract)