query_ontology
Run graph-database-style queries over a compiled ontology to trace dependencies, paths, impact, reachability, and schema without pulling the full compile payload.
Instructions
Analysis archive: analysis_history reads immutable diagnostic Markdown summaries without compiling the graph; use analysisMode, project, limit (1–100 scanned files, default 30), and analysisCursor. analysis_record reads one exact run or review with recordId (UUID). Records retain raw answers, full-body evidence when available, request scope and uncertainty. They are not approved ontology facts; stored qualification describes captured evidence, never current source validity. Reviews are joined to their exact run/finding id. Follow pagination even if a filtered page is empty. These archive operations do not support query_plan. Run graph-engine queries over the freshly compiled ontology artifact. Operations: neighbors (local graph neighborhood), path (one compiled-edge route between two nodes with aligned nodes[] summaries), all_paths (bounded simple paths between two nodes with per-path nodes[] summaries plus limit/searchBudget/exhaustive/truncatedByBudget/totalPathsExact metadata and evidence guidance), query_plan (EXPLAIN-style side-effect-free cost/index estimate plus execution advice before a target operation, filter-preserving suggestedQuery, and filter-aware estimate.totalMatches for match_nodes/match_edges), centrality (PageRank-style core-node ranking plus bridge/authority/hub lists), communities (label-propagation clusters inside the graph), similar_nodes (duplicate/overlap candidates before writes), explain_relation (direct edges, shortest path, and shared-neighbor explanation between two nodes), reachability (transitive graph closure from a start node), pattern_walk (explicit relation-sequence paths such as project → domains → capabilities), impact (incoming by default: what depends on this node), blast_radius (impact grouped by kind/domain with cross-domain edge risk), subgraph (bounded N-hop graph slice for UI/agent views), builder_context (persisted Workshop focus, layout positions, direct graph slice, and safe write handoff; unsaved UI drafts are explicitly excluded; operation name retained for compatibility), overview (counts, relation distribution, and hubs), schema (kind-relation-kind patterns), facets (filter/dashboard aggregates), match_nodes (graph DB-style node rows with degree filters plus a followUp packet for the first returned row), match_edges (graph DB-style edge pattern rows plus a followUp packet for the first returned real edge), node_profile (single node detail dashboard), domain_profile (domain detail dashboard), domain_matrix (domain-to-domain coupling), project_scope (project-contained graph slice), project_map (domain-by-domain project map), relation_check (schema-aware preflight before add_relation), components (connected graph islands), lineage and containment_tree (project/domain/capability containment), cycles (directed dependency-cycle checks), topological_order (prerequisite-first dependency ordering), recommend_relations (safe domain-containment suggestions), growth_plan (side-effect-free ontology expansion candidates, plus a nextReads group that turns the ## Uncertainty section of each node into the reads it asks for: kind, the statement as written, the paths and line ranges it names, and a one-sentence proposed read plus patch_concept, ordered cheapest-first and reporting reason: no_bodies when no node bodies were loaded), maintenance_plan (ordered post-write graph cleanup/repair actions with stable action id, count-safe summary fields, byPhase / bySeverity / byKind remaining-queue buckets, ready cursor cursor.found=true / cursor.reason=null, cursor nextAfterActionId/hasMore pagination metadata, afterActionId resume, unknown-cursor empty page with cursor.nextAfterActionId=null / cursor.hasMore=false, kind filters, executable graph-array canonicalization, executable flags, and current-page nextExecutableAction / nextReviewAction pointers), agent_brief (Claude Code/Codex handoff prompt, structured businessOntologyLens with business-first outcome → domain → capability → element read order, graphDbQueryPack for facets, schema, match_nodes, match_edges, domain_matrix, centrality, all_paths, explain_relation, and business_questions scans for outcome / domain boundary / capability claim nodes / implementation evidence edges, structured cliFallbackCommands, recipes, graph entrypoints, graph_traversal playbook, traversalStrategy plan_before_enumeration/bounded_path_evidence/containment_cross_check guidance, playbook evidence/stopWhen checklists, write guardrails, relationDecisionGuide, resultContracts for all_paths completeness and match_nodes/match_edges followUp evidence, and read-first write policy), meaning_repair_review (provenance-bound, byte-bounded typed evidence pages and literal full-body read calls for the compact meaning repair manifest), workspace_brief (first-contact status + next actions), and health (one-shot graph integrity dashboard whose relationCensus labels compiler declaration counts and the nonnumeric canonical app-map comparison unit). For agent_brief, select project explicitly when the vault has more than one project. Omitted detail and detail:"full" return the complete project-scoped diagnostic contract. For a known coding task, call detail:"compact" directly after connection_info; do not precede it with workspace_brief or a full inventory unless the question needs whole-vault health. Compact v2 requires a nonblank request-local task (max 2000 characters) and returns at most 12000 UTF-8 JSON bytes: final source/meaning currentness, claim-compatible broad capability selection, persisted element/path evidence, explicit unknown impact and verification, exact full-body next reads, and a detail:"full" follow-up. Definition and Includes support desired work; Excludes may align with explicit non-goals, while a desired/negative boundary conflict, an unsupported claim, or a tied top claim returns no capability. Its content[0].text is the bounded handoff prompt while structuredContent carries the typed facts once. When the selected element Markdown contains reviewed Primary implementation / Supporting implementation / Focused test coordinates and the bound source is current, taskNavigation verifies only those named files and returns exact current lines plus the reviewed non-exhaustive IN/OUT boundary. After those reads, Atlas rechecks the same source identity, fingerprint, revision, and graph hash; any mismatch removes the exact target and downgrades the complete outer currentness contract. A ready prompt reads primary, supporting, focused tests, and a verified manifest together; requires named positive and negative regression tests with exact observable output; and runs the focused check once followed by one non-overlapping full check. Missing, ambiguous, stale, unsafe, or unrecorded coordinates emit no exact target. Task matching selects evidence only; it never searches the repository, never proves source behavior, never persists task text, never approves meaning, and never writes the vault. For impact and blast_radius, only declared depends_on is allowed; use reachability/subgraph for structure. Blast radius reports unknown risk/completeness plus review_required or declared_with_rationale edge qualification until relation-level source receipts exist. A missing depends_on preflight is schema-only: relation_check returns proposedAction:null plus a non-writing approvalGate until the agent explains the observable ability and semantic rationale and receives explicit human approval. Accepts canonical slugs or unique aliases. side effect 0. Use this when you need graph-database-like answers without pulling the full compile_ontology payload.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Target node slug or unique alias. Required for path, all_paths, and explain_relation. | |
| from | No | Source node slug or unique alias. Required for path, all_paths, and explain_relation. | |
| kind | No | match_nodes: optional node kind filter (project, domain, capability, element, document, vault-readme). recommend_relations currently supports capability or element. | |
| seed | No | Alias for slug when operation is subgraph or builder_context. | |
| slug | No | Center/root node slug or unique alias. builder_context also accepts its own canonical Workshop focusParam (for example domain:auth). Required for neighbors, reachability, pattern_walk, impact, blast_radius, subgraph, builder_context, lineage, node_profile, and domain_profile; optional root for containment_tree. | |
| sort | No | match_nodes only: sort rows by degree, inDegree, outDegree, or slug. Defaults to degree. | |
| task | No | agent_brief detail:"compact" only: request-local coding task used to select persisted capability, element, and reviewed navigation evidence after Definition/Includes/Excludes compatibility. Conflicting, unsupported, or tied claims return no capability. Never persisted, never used to invent a coordinate, and never treated as behavior proof or semantic approval. | |
| type | No | Relation type for relation_check/match_edges, e.g. depends_on, relates, contains, describes, domains, capabilities, elements, or domain. | |
| depth | No | reachability/impact/blast_radius/subgraph/lineage/containment_tree traversal depth. Defaults to 3 for reachability, 2 for impact/blast_radius/subgraph, and 20 for lineage/containment_tree; capped at 20. | |
| kinds | No | maintenance_plan only: optional action-kind filter, e.g. ["add_missing_relation", "canonicalize_graph_arrays"]. | |
| limit | No | Positive integer max rows/components/order entries to return. Defaults to 100, capped at 500. | |
| title | No | similar_nodes only: proposed title for a not-yet-written concept candidate. | |
| types | No | Optional relation types to include, e.g. ["dependencies"] or ["depends_on"]. | |
| cursor | No | meaning_repair_review only: opaque stateless cursor returned as pagination.nextCursor. Omit for the first page. | |
| detail | No | agent_brief only: compact v2 returns a task-scoped, selected-project handoff capped at 12000 UTF-8 JSON bytes, including exact reviewed taskNavigation only when the bound source is current; full returns the complete diagnostic manuals and graph packs. Omit to keep the current full response while compact is being qualified. | |
| domain | No | match_nodes: optional exact domain filter. domain_profile: domain root slug or unique alias. | |
| phases | No | maintenance_plan only: optional phase filter, e.g. ["repair", "link", "materialize"]. | |
| toKind | No | match_edges only: optional target kind filter (project, domain, capability, element, document, vault-readme, external, unresolved). Use external or unresolved for non-node refs. | |
| maxHops | No | path/all_paths/explain_relation traversal hop cap or cycles max depth. Defaults to 5 for path/all_paths/explain_relation and 8 for cycles; capped at 20. | |
| pattern | No | pattern_walk only: required relation sequence to follow, e.g. ["domains", "capabilities", "elements"]. depends_on is normalized to dependencies. | |
| project | No | domain_matrix/project_scope/project_map/agent_brief/meaning_repair_review: project root slug or unique alias. Required for meaning_repair_review; optional when exactly one kind: project node exists for the other operations. | |
| fromKind | No | match_edges only: optional source node kind filter (project, domain, capability, element, document, vault-readme). Source must be a real ontology node, not external/unresolved. | |
| recordId | No | analysis_record only: immutable analysis or diagnostic-review UUID. | |
| relation | No | Alias for type when operation is relation_check. | |
| direction | No | neighbors/reachability/impact/blast_radius/subgraph/builder_context: incoming, outgoing, or both. path/all_paths/explain_relation/reachability also accepts undirected. | |
| itemLimit | No | project_map only: positive integer max capability/element/hotspot summaries per domain. Defaults to 20, capped at 500. | |
| maxDegree | No | match_nodes only: non-negative integer maximum total graph degree. | |
| minDegree | No | match_nodes only: non-negative integer minimum total graph degree. | |
| nodeLimit | No | components/communities/health/workspace_brief/agent_brief only: positive integer max node summaries per component/community group. Defaults to 25 for components/communities and 10 for health, capped at 500. | |
| operation | Yes | Query operation to run. | |
| cycleLimit | No | health/workspace_brief/agent_brief only: positive integer max dependency cycles to inspect. Defaults to 5, capped at 500. | |
| iterations | No | centrality/communities only: positive integer PageRank or label-propagation iteration count. Defaults to 20, max 100. | |
| orderLimit | No | health/workspace_brief/agent_brief only: positive integer max topological-order rows to inspect. Defaults to 20, capped at 500. | |
| severities | No | maintenance_plan only: optional severity filter, e.g. ["fail", "warn"]. | |
| hasIncoming | No | match_nodes only: require presence or absence of incoming graph edges. | |
| hasOutgoing | No | match_nodes only: require presence or absence of outgoing graph edges. | |
| minInDegree | No | match_nodes only: non-negative integer minimum incoming graph degree. | |
| analysisMode | No | analysis_history only: optional analysis subject filter. | |
| minOutDegree | No | match_nodes only: non-negative integer minimum outgoing graph degree. | |
| searchBudget | No | all_paths, query_plan(all_paths), and cycles: maximum DFS states to expand before returning partial results. Defaults to 5000. For cycles, `limit` trims only the listed rows and this budget is the one bound that can cut the count short — when truncatedByBudget is true, totalCycles is a lower bound and zero cycles does NOT mean acyclic (check totalCyclesExact). | |
| slugContains | No | match_nodes only: optional case-insensitive substring filter on canonical slug. | |
| afterActionId | No | maintenance_plan only: stable action id cursor; return actions after this id. Without afterActionId the ready page reports cursor.found=true and cursor.reason=null; cursor.nextAfterActionId matches the last returned action id (or null for an empty page), and cursor.hasMore matches whether more remaining actions exist after this page. nextExecutableAction/nextReviewAction point only at the first executable/review action in the current returned page and preserve that action id, executable flag, phase, kind, and severity. Bucket totals (byPhase, bySeverity, byKind) match remainingActions for the returned cursor. Unknown cursors return an empty page with cursor.found=false, cursor.reason, zero remaining actions, cursor.nextAfterActionId=null, cursor.hasMore=false, and no next actions. | |
| candidateSlug | No | similar_nodes only: proposed slug for a not-yet-written concept candidate. | |
| analysisCursor | No | analysis_history only: nextCursor from the preceding scanned-file page. | |
| componentLimit | No | health/workspace_brief/agent_brief only: positive integer max connected components to inspect. Defaults to 5, capped at 500. | |
| componentTypes | No | health/workspace_brief/agent_brief only: relation types used for connected-component checks. Defaults to the full graph relation set. | |
| executableOnly | No | maintenance_plan only: when true, return only actions with a proposed tool call. | |
| includeOrphans | No | containment_tree only: include ancestorless nodes not reached from project roots. Defaults false. | |
| reviewRevision | No | meaning_repair_review only: sha256 revision from meaningRepair:v2, binding graph/source/typed rows/target mtimes. | |
| dependencyTypes | No | health/workspace_brief/agent_brief only: dependency relation types used for cycle and topological-order checks. Defaults to ["dependencies"]. | |
| includeExternal | No | neighbors only: include external path-like element refs. Defaults false. | |
| includeIsolated | No | topological_order only: include nodes that are not connected by the selected relation types. Defaults false. | |
| targetOperation | No | query_plan only: read-only graph operation to explain before execution. Excludes query_plan, meaning_repair_review, analysis_history and analysis_record. | |
| expectedGraphHash | No | meaning_repair_review first page: exact graphHash from meaningRepair:v2 provenance. Later nextCall values are revision-bound and omit it. | |
| includeUnresolved | No | neighbors only: include dangling unresolved refs. Defaults false. | |
| recommendationLimit | No | health/workspace_brief/agent_brief only: positive integer max relation recommendations to inspect. Defaults to 20, capped at 500. | |
| expectedSourceFingerprint | No | meaning_repair_review first page: exact current sourceFingerprint from meaningRepair:v2 provenance. Later nextCall values are revision-bound and omit it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| compiledSummary | No |