@haaaiawd/anws 2.3.0 → 2.4.0

package/templates_en/.agents/skills/nexus-mapper/scripts/query_graph.py

@@ -0,0 +1,556 @@
+#!/usr/bin/env python3
+"""
+query_graph.py — On-demand AST query tool
+
+Read ast_nodes.json produced by extract_ast.py and provide multiple query modes,
+output concise text that is easy for agents to consume.
+
+Purpose: 
+  - Assist REASON/OBJECT/EMIT stages in the PROBE workflow to generate cognition files
+  - Perform bug investigation, change impact analysis, and refactor analysis during development
+
+Usage: 
+  python query_graph.py <ast_nodes.json> --file <path>
+  python query_graph.py <ast_nodes.json> --who-imports <module_or_path>
+  python query_graph.py <ast_nodes.json> --impact <path>
+  python query_graph.py <ast_nodes.json> --hub-analysis [--top N]
+  python query_graph.py <ast_nodes.json> --summary
+"""
+
+import sys
+import json
+import argparse
+from pathlib import Path, PurePosixPath
+from collections import defaultdict
+
+
+class GitStats:
+    """Query helper for git_stats.json. Optional loading, no impact on core AST queries."""
+
+    def __init__(self, data: dict):
+        self.period_days: int = data.get('analysis_period_days', 90)
+        self.hotspots: dict[str, dict] = {}  # path → {changes, risk}
+        for h in data.get('hotspots', []):
+            self.hotspots[h['path']] = h
+        self.coupling: dict[str, list[dict]] = defaultdict(list)  # path → [{peer, co_changes, score}]
+        for c in data.get('coupling_pairs', []):
+            self.coupling[c['file_a']].append({
+                'peer': c['file_b'], 'co_changes': c['co_changes'],
+                'score': c['coupling_score'],
+            })
+            self.coupling[c['file_b']].append({
+                'peer': c['file_a'], 'co_changes': c['co_changes'],
+                'score': c['coupling_score'],
+            })
+
+    def file_risk(self, path: str) -> dict | None:
+        return self.hotspots.get(path)
+
+    def file_coupling(self, path: str) -> list[dict]:
+        return sorted(self.coupling.get(path, []), key=lambda x: x['score'], reverse=True)
+
+    RISK_ICON = {'high': '🔴', 'medium': '🟡', 'low': '🟢'}
+
+    def format_risk_block(self, path: str) -> list[str]:
+        """Generate git risk + coupling text lines for a file (empty list means no data)."""
+        lines: list[str] = []
+        risk = self.file_risk(path)
+        if risk:
+            icon = self.RISK_ICON.get(risk['risk'], '⚪')
+            lines.append(f"Git risk: {icon} {risk['risk']} ({risk['changes']} changes in {self.period_days} days)")
+        coupling = self.file_coupling(path)
+        if coupling:
+            lines.append("Coupled files (co-change):")
+            for c in coupling[:5]:
+                lines.append(f"  - {c['peer']} (coupling: {c['score']:.2f}, {c['co_changes']} co-changes)")
+        return lines
+
+
+class ASTGraph:
+    """In-memory AST graph index supporting multiple query modes."""
+
+    SOURCE_ROOT_MARKERS = (
+        ('src',),
+        ('backend', 'src'),
+        ('frontend', 'src'),
+        ('client', 'src'),
+        ('src', 'main', 'python'),
+        ('src', 'test', 'python'),
+        ('src', 'main', 'java'),
+        ('src', 'test', 'java'),
+        ('src', 'main', 'kotlin'),
+        ('src', 'test', 'kotlin'),
+    )
+
+    def __init__(self, data: dict, git_stats: GitStats | None = None):
+        self.data = data
+        self.nodes: list[dict] = data.get('nodes', [])
+        self.edges: list[dict] = data.get('edges', [])
+        self.stats: dict = data.get('stats', {})
+        self.languages: list[str] = data.get('languages', [])
+        self.git: GitStats | None = git_stats
+
+        # Indexes
+        self.nodes_by_id: dict[str, dict] = {}
+        self.nodes_by_path: dict[str, list[dict]] = defaultdict(list)
+        self.modules_by_path: dict[str, dict] = {}
+        self.imports_forward: dict[str, set[str]] = defaultdict(set)
+        self.imports_reverse: dict[str, set[str]] = defaultdict(set)
+        self.internal_imports_forward: dict[str, set[str]] = defaultdict(set)
+        self.internal_imports_reverse: dict[str, set[str]] = defaultdict(set)
+        self.contains_children: dict[str, list[dict]] = defaultdict(list)
+        self.path_to_module_id: dict[str, str] = {}
+        self.alias_to_module_ids: dict[str, set[str]] = defaultdict(set)
+
+        self._build_index()
+
+    def _build_index(self) -> None:
+        for node in self.nodes:
+            nid = node['id']
+            self.nodes_by_id[nid] = node
+            path = node.get('path', '')
+            if path:
+                self.nodes_by_path[path].append(node)
+            if node['type'] == 'Module' and path:
+                self.modules_by_path[path] = node
+                self.path_to_module_id[path] = nid
+                for alias in self._module_aliases(nid, path):
+                    self.alias_to_module_ids[alias].add(nid)
+
+        for edge in self.edges:
+            src, tgt, etype = edge['source'], edge['target'], edge['type']
+            if etype == 'imports':
+                self.imports_forward[src].add(tgt)
+                self.imports_reverse[tgt].add(src)
+            elif etype == 'contains':
+                child = self.nodes_by_id.get(tgt)
+                if child:
+                    self.contains_children[src].append(child)
+
+        module_ids = {n['id'] for n in self.nodes if n['type'] == 'Module'}
+        for source, targets in self.imports_forward.items():
+            if source not in module_ids:
+                continue
+            for target in targets:
+                resolved = self.resolve_import_target(target)
+                if resolved and resolved in module_ids and resolved != source:
+                    self.internal_imports_forward[source].add(resolved)
+                    self.internal_imports_reverse[resolved].add(source)
+
+    def _module_aliases(self, module_id: str, path: str) -> set[str]:
+        aliases = {module_id}
+        parts = list(PurePosixPath(path.replace('\\', '/')).parts)
+        if not parts:
+            return aliases
+
+        stem = PurePosixPath(parts[-1]).stem
+        normalized_parts = parts[:-1] if stem == '__init__' else parts[:-1] + [stem]
+
+        for marker in self.SOURCE_ROOT_MARKERS:
+            if tuple(normalized_parts[:len(marker)]) == marker and len(normalized_parts) > len(marker):
+                aliases.add('.'.join(normalized_parts[len(marker):]))
+
+        for idx, part in enumerate(normalized_parts):
+            if part == 'src' and idx + 1 < len(normalized_parts):
+                aliases.add('.'.join(normalized_parts[idx + 1:]))
+
+        return {alias for alias in aliases if alias}
+
+    def resolve_import_target(self, target: str) -> str | None:
+        if target in self.nodes_by_id and self.nodes_by_id[target]['type'] == 'Module':
+            return target
+
+        direct = self.alias_to_module_ids.get(target)
+        if direct and len(direct) == 1:
+            return next(iter(direct))
+
+        parts = target.split('.')
+        while len(parts) > 1:
+            parts = parts[:-1]
+            candidate = '.'.join(parts)
+            matches = self.alias_to_module_ids.get(candidate)
+            if matches and len(matches) == 1:
+                return next(iter(matches))
+
+        return None
+
+    def _classify_imports(self, imports: set[str]) -> tuple[list[tuple[str, str]], list[str]]:
+        internal: list[tuple[str, str]] = []
+        external: list[str] = []
+        for imp in sorted(imports):
+            resolved = self.resolve_import_target(imp)
+            if resolved:
+                internal.append((imp, resolved))
+            else:
+                external.append(imp)
+        return internal, external
+
+    def resolve_to_module_id(self, query: str) -> str | None:
+        """Resolve file path or module id to module id."""
+        # Try direct module id lookup
+        if query in self.nodes_by_id and self.nodes_by_id[query]['type'] == 'Module':
+            return query
+        # Try as file path (compatible with \\ and /)
+        normalized = query.replace('\\', '/')
+        if normalized in self.path_to_module_id:
+            return self.path_to_module_id[normalized]
+        # Fuzzy match: remove leading repo-relative path prefix
+        for path, mid in self.path_to_module_id.items():
+            if path.endswith(normalized) or normalized.endswith(path):
+                return mid
+        return None
+
+    def resolve_to_path(self, module_id: str) -> str | None:
+        """Resolve module id to file path."""
+        node = self.nodes_by_id.get(module_id)
+        if node:
+            return node.get('path')
+        return None
+
+    # ── Query mode implementation ──────────────────────────────────────────────
+
+    def query_file(self, file_query: str) -> str:
+        """--file: Show full structure and import list for a file."""
+        mid = self.resolve_to_module_id(file_query)
+        if not mid:
+            return f"[NOT FOUND] No module matching '{file_query}'"
+
+        module_node = self.nodes_by_id[mid]
+        path = module_node.get('path', mid)
+        lines = module_node.get('lines', '?')
+        lang = module_node.get('lang', '?')
+
+        out = [f"=== {path} ==="]
+        out.append(f"Module: {mid} ({lines} lines, {lang})")
+        out.append("")
+
+        # Classes and functions
+        classes = [n for n in self.contains_children.get(mid, []) if n['type'] == 'Class']
+        top_funcs = [n for n in self.contains_children.get(mid, []) if n['type'] == 'Function']
+
+        if classes:
+            out.append("Classes:")
+            for cls in classes:
+                sl = cls.get('start_line', '?')
+                el = cls.get('end_line', '?')
+                out.append(f"  {cls['label']} (L{sl}-L{el})")
+                methods = [n for n in self.contains_children.get(cls['id'], []) if n['type'] == 'Function']
+                for i, m in enumerate(methods):
+                    prefix = "└─" if i == len(methods) - 1 else "├─"
+                    ml = m.get('start_line', '?')
+                    me = m.get('end_line', '?')
+                    out.append(f"    {prefix} {m['label']} (L{ml}-L{me})")
+            out.append("")
+
+        if top_funcs:
+            out.append("Top-level Functions:")
+            for f in top_funcs:
+                sl = f.get('start_line', '?')
+                el = f.get('end_line', '?')
+                out.append(f"  {f['label']} (L{sl}-L{el})")
+            out.append("")
+
+        # Imports
+        imports = sorted(self.imports_forward.get(mid, set()))
+        if imports:
+            internal, external = self._classify_imports(set(imports))
+            out.append("Imports:")
+            for raw_imp, resolved_imp in internal:
+                imp_path = self.resolve_to_path(resolved_imp)
+                suffix = f" ({imp_path})" if imp_path else ""
+                if raw_imp == resolved_imp:
+                    out.append(f"  → {raw_imp}{suffix}")
+                else:
+                    out.append(f"  → {raw_imp}  [resolved: {resolved_imp}{suffix}]")
+            for imp in external:
+                out.append(f"  → {imp} (external)")
+            out.append("")
+
+        if not classes and not top_funcs and not imports:
+            out.append("(no classes, functions, or imports detected)")
+
+        # Git stats (optional)
+        if self.git:
+            git_lines = self.git.format_risk_block(path)
+            if git_lines:
+                out.append("Git:")
+                out.extend(f"  {l}" for l in git_lines)
+                out.append("")
+
+        return "\n".join(out)
+
+    def query_who_imports(self, module_query: str) -> str:
+        """--who-imports: Reverse dependency query."""
+        mid = self.resolve_to_module_id(module_query)
+
+        # Also try direct lookup in imports_reverse (for external package names, etc.)
+        if not mid:
+            # Could be a partial match (e.g. 'flask' in import targets)
+            matches = set()
+            normalized = module_query.replace('\\', '/')
+            for target, sources in self.imports_reverse.items():
+                if target == normalized or target == module_query:
+                    matches.update(sources)
+            if matches:
+                return self._format_who_imports(module_query, matches)
+            return f"[NOT FOUND] No module matching '{module_query}'"
+
+        importers: set[str] = set(self.internal_imports_reverse.get(mid, set()))
+
+        return self._format_who_imports(mid, importers)
+
+    def _format_who_imports(self, query: str, importers: set[str]) -> str:
+        out = [f"=== Who imports {query}? ==="]
+        if not importers:
+            out.append("Not imported by any module in the project.")
+            return "\n".join(out)
+
+        out.append(f"Imported by {len(importers)} module(s):")
+        for imp in sorted(importers):
+            imp_path = self.resolve_to_path(imp)
+            suffix = f" ({imp_path})" if imp_path else ""
+            out.append(f"  ← {imp}{suffix}")
+        return "\n".join(out)
+
+    def query_impact(self, file_query: str) -> str:
+        """--impact: Impact radius analysis (upstream/downstream dependencies)."""
+        mid = self.resolve_to_module_id(file_query)
+        if not mid:
+            return f"[NOT FOUND] No module matching '{file_query}'"
+
+        module_node = self.nodes_by_id[mid]
+        path = module_node.get('path', mid)
+
+        out = [f"=== Impact radius: {path} ===", ""]
+
+        # Upstream: what this file imports
+        forward = sorted(self.imports_forward.get(mid, set()))
+        internal_forward, external_forward = self._classify_imports(set(forward))
+
+        out.append("Depends on (this file imports):")
+        if internal_forward:
+            for raw_dep, resolved_dep in internal_forward:
+                dep_path = self.resolve_to_path(resolved_dep)
+                suffix = f" ({dep_path})" if dep_path else ""
+                if raw_dep == resolved_dep:
+                    out.append(f"  → {raw_dep}{suffix}")
+                else:
+                    out.append(f"  → {raw_dep}  [resolved: {resolved_dep}{suffix}]")
+        if external_forward:
+            for dep in external_forward:
+                out.append(f"  → {dep} (external)")
+        if not forward:
+            out.append("  (none)")
+        out.append("")
+
+        # Downstream: who imports this file
+        importers: set[str] = set(self.internal_imports_reverse.get(mid, set()))
+
+        out.append("Depended by (other files import this):")
+        if importers:
+            for imp in sorted(importers):
+                imp_path = self.resolve_to_path(imp)
+                suffix = f" ({imp_path})" if imp_path else ""
+                out.append(f"  ← {imp}{suffix}")
+        else:
+            out.append("  (none)")
+        out.append("")
+
+        downstream_count = len(importers)
+        upstream_count = len({resolved for _raw, resolved in internal_forward})
+        out.append(
+            f"Impact summary: {upstream_count} upstream dependencies, "
+            f"{downstream_count} downstream dependents"
+        )
+
+        # Git stats (optional)
+        if self.git:
+            out.append("")
+            git_lines = self.git.format_risk_block(path)
+            if git_lines:
+                out.extend(git_lines)
+
+        return "\n".join(out)
+
+    def query_hub_analysis(self, top_n: int = 10) -> str:
+        """--hub-analysis: Identify core nodes with high fan-in/fan-out."""
+        fan_in = {target: len(sources) for target, sources in self.internal_imports_reverse.items()}
+        fan_out = {source: len(targets) for source, targets in self.internal_imports_forward.items()}
+
+        out = ["=== Hub Analysis ===", ""]
+
+        # Top fan-in
+        top_fan_in = sorted(fan_in.items(), key=lambda x: x[1], reverse=True)[:top_n]
+        out.append("Top fan-in (most imported by others):")
+        if top_fan_in:
+            for i, (mid, count) in enumerate(top_fan_in, 1):
+                path = self.resolve_to_path(mid) or ""
+                out.append(f"  {i}. {mid} — imported by {count} module(s)  [{path}]")
+        else:
+            out.append("  (no internal import relationships found)")
+        out.append("")
+
+        # Top fan-out
+        top_fan_out = sorted(fan_out.items(), key=lambda x: x[1], reverse=True)[:top_n]
+        out.append("Top fan-out (imports most others):")
+        if top_fan_out:
+            for i, (mid, count) in enumerate(top_fan_out, 1):
+                path = self.resolve_to_path(mid) or ""
+                out.append(f"  {i}. {mid} — imports {count} internal module(s)  [{path}]")
+        else:
+            out.append("  (no internal import relationships found)")
+
+        return "\n".join(out)
+
+    def query_summary(self) -> str:
+        """--summary: Structural summary aggregated by top-level directories."""
+        # Aggregate by first-level or second-level directory
+        dir_stats: dict[str, dict] = defaultdict(
+            lambda: {'modules': 0, 'classes': 0, 'functions': 0, 'lines': 0,
+                     'class_names': [], 'import_dirs': set()}
+        )
+
+        # Aggregation granularity: use first 2 path levels
+        def _dir_key(path: str) -> str:
+            parts = path.split('/')
+            if len(parts) <= 2:
+                return parts[0] + '/'
+            return '/'.join(parts[:2]) + '/'
+
+        for node in self.nodes:
+            path = node.get('path', '')
+            if not path:
+                continue
+            dk = _dir_key(path)
+            ntype = node['type']
+            if ntype == 'Module':
+                dir_stats[dk]['modules'] += 1
+                dir_stats[dk]['lines'] += node.get('lines', 0)
+            elif ntype == 'Class':
+                dir_stats[dk]['classes'] += 1
+                dir_stats[dk]['class_names'].append(node['label'])
+            elif ntype == 'Function':
+                dir_stats[dk]['functions'] += 1
+
+        # Collect import source directories for each directory
+        for mid, targets in self.imports_forward.items():
+            src_node = self.nodes_by_id.get(mid)
+            if not src_node or src_node['type'] != 'Module':
+                continue
+            src_path = src_node.get('path', '')
+            if not src_path:
+                continue
+            src_dk = _dir_key(src_path)
+            for t in targets:
+                t_node = self.nodes_by_id.get(t)
+                if t_node and t_node.get('path'):
+                    t_dk = _dir_key(t_node['path'])
+                    if t_dk != src_dk:
+                        dir_stats[src_dk]['import_dirs'].add(t_dk.rstrip('/'))
+
+        out = ["=== Directory Summary ===", ""]
+
+        for dk in sorted(dir_stats.keys()):
+            s = dir_stats[dk]
+            out.append(
+                f"{dk} ({s['modules']} modules, {s['classes']} classes, "
+                f"{s['functions']} functions, {s['lines']} lines)"
+            )
+            if s['class_names']:
+                # Show at most 8
+                names = s['class_names'][:8]
+                suffix = f" ... +{len(s['class_names']) - 8}" if len(s['class_names']) > 8 else ""
+                out.append(f"  Key classes: {', '.join(names)}{suffix}")
+            import_dirs = sorted(s['import_dirs'])
+            if import_dirs:
+                out.append(f"  Key imports from: {', '.join(import_dirs)}")
+            else:
+                out.append(f"  Key imports from: (none / external only)")
+            out.append("")
+
+        if not dir_stats:
+            out.append("(no modules found in ast_nodes.json)")
+
+        return "\n".join(out)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description='Query AST graph from ast_nodes.json',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  %(prog)s ast_nodes.json --file src/server/handler.py
+  %(prog)s ast_nodes.json --who-imports src.server.handler
+  %(prog)s ast_nodes.json --impact src/server/handler.py
+  %(prog)s ast_nodes.json --hub-analysis --top 10
+  %(prog)s ast_nodes.json --summary
+""",
+    )
+    parser.add_argument('ast_json', help='Path to ast_nodes.json')
+    parser.add_argument('--file', dest='file_query', help='Show structure and imports of a file')
+    parser.add_argument('--who-imports', dest='who_imports', help='Find modules that import the given module')
+    parser.add_argument('--impact', dest='impact_query', help='Show impact radius (deps + dependents)')
+    parser.add_argument('--hub-analysis', action='store_true', help='Show top fan-in/fan-out modules')
+    parser.add_argument('--summary', action='store_true', help='Show per-directory structural summary')
+    parser.add_argument('--top', type=int, default=10, help='Number of results for hub-analysis (default: 10)')
+    parser.add_argument('--git-stats', dest='git_stats_path', metavar='GIT_STATS_JSON',
+                        help='Optional git_stats.json to enrich --file and --impact with risk/coupling data')
+
+    args = parser.parse_args()
+
+    # Ensure at least one query mode is provided
+    has_query = any([args.file_query, args.who_imports, args.impact_query,
+                     args.hub_analysis, args.summary])
+    if not has_query:
+        parser.print_help()
+        sys.exit(1)
+
+    # Load JSON
+    ast_path = Path(args.ast_json)
+    if not ast_path.exists():
+        sys.stderr.write(f"[ERROR] File not found: {ast_path}\n")
+        sys.exit(1)
+
+    try:
+        raw_text = ast_path.read_text(encoding='utf-8')
+        # Skip possible mixed-in stderr lines (e.g. [WARNING]); parse from first '{'
+        json_start = raw_text.find('{')
+        if json_start < 0:
+            sys.stderr.write(f"[ERROR] No JSON object found in {ast_path}\n")
+            sys.exit(1)
+        data = json.loads(raw_text[json_start:])
+    except json.JSONDecodeError as e:
+        sys.stderr.write(f"[ERROR] Invalid JSON: {e}\n")
+        sys.exit(1)
+
+    # Optionally load git stats
+    git_stats: GitStats | None = None
+    if args.git_stats_path:
+        gs_path = Path(args.git_stats_path)
+        if not gs_path.exists():
+            sys.stderr.write(f"[WARNING] git_stats file not found: {gs_path}, ignoring\n")
+        else:
+            try:
+                gs_data = json.loads(gs_path.read_text(encoding='utf-8'))
+                git_stats = GitStats(gs_data)
+            except (json.JSONDecodeError, KeyError) as e:
+                sys.stderr.write(f"[WARNING] git_stats parse error: {e}, ignoring\n")
+
+    graph = ASTGraph(data, git_stats=git_stats)
+
+    # Execute query
+    if args.file_query:
+        print(graph.query_file(args.file_query))
+    elif args.who_imports:
+        print(graph.query_who_imports(args.who_imports))
+    elif args.impact_query:
+        print(graph.query_impact(args.impact_query))
+    elif args.hub_analysis:
+        print(graph.query_hub_analysis(args.top))
+    elif args.summary:
+        print(graph.query_summary())
+
+
+if __name__ == '__main__':
+    main()

package/templates_en/.agents/skills/nexus-mapper/scripts/requirements.txt

@@ -0,0 +1,6 @@
+# nexus-mapper scripts dependencies
+# For standalone use or distribution installation
+# When used inside the Nexus project, dependencies are already covered by the poetry environment (tree-sitter ^0.25.2 + tree-sitter-language-pack)
+
+tree-sitter>=0.22.0
+tree-sitter-language-pack

package/templates_en/.agents/skills/nexus-query/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: nexus-query
+description: "Precise, instant code structure queries for active development — answer 'who depends on this interface before I refactor it', 'how many modules break if I change this', 'what is the real impact radius of this feature change', 'which module is the true high-coupling hotspot in this legacy codebase'. Essential before any interface change, continuous refactoring task, sprint work estimation, or when navigating unfamiliar or large legacy codebases. Requires Python 3.10+ and shell. Use nexus-mapper instead when building a full .nexus-map/ knowledge base."
+---
+
+# nexus-query — Precise Code Structure Queries
+
+
+## When to Use
+
+| Scenario | Use |
+|------|:----:|
+| "What classes/methods are in this file, and what does it depend on?" | Yes |
+| "If I change this interface/module, which files are affected?" | Yes |
+| "What is the impact radius of this change?" | Yes |
+| "Which node is the true core dependency in this project?" | Yes |
+| "How is the project roughly partitioned?" | Yes |
+| User wants to generate full `.nexus-map/` knowledge base | No -> use nexus-mapper |
+| Runtime has no shell execution capability | No |
+| Host has no local Python 3.10+ | No |
+
+---
+
+## Prerequisite: Ensure ast_nodes.json Exists
+
+```
+Before querying -> check if ast_nodes.json exists
+├── Exists (.nexus-map/raw/ast_nodes.json or user-provided path) -> query directly
+└── Missing -> run extract_ast.py to generate -> then query
+```
+
+```bash
+# Default paths (compatible with nexus-mapper .nexus-map/, interchangeable)
+AST_JSON="$repo_path/.nexus-map/raw/ast_nodes.json"
+GIT_JSON="$repo_path/.nexus-map/raw/git_stats.json"    # optional
+
+# If ast_nodes.json is missing, create dir first, then generate (usually seconds)
+mkdir -p "$repo_path/.nexus-map/raw"
+python $SKILL_DIR/scripts/extract_ast.py $repo_path > $AST_JSON
+
+# If git risk data needed (optional, only when .git exists)
+python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 > $GIT_JSON
+```
+
+> `$SKILL_DIR` is this skill's install path (`.agent/skills/nexus-query` or standalone repo path).
+
+**Dependency install (first use)**:
+```bash
+pip install -r $SKILL_DIR/scripts/requirements.txt
+```
+
+---
+
+## Five Query Modes
+
+```bash
+# File skeleton: classes, methods, line numbers, import list
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path>
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --file <path> --git-stats $GIT_JSON
+
+# Reverse dependency: who imports this module (separates source and test files)
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --who-imports <module_or_path>
+
+# Impact radius: upstream dependencies + downstream dependents (X upstream, Y downstream)
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path>
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --impact <path> --git-stats $GIT_JSON
+
+# Core repo nodes: rank by fan-in (most referenced) and fan-out (references most)
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --hub-analysis [--top N]
+
+# Aggregate structural summary by top-level directory
+python $SKILL_DIR/scripts/query_graph.py $AST_JSON --summary
+```
+
+### Core Value of Each Mode
+
+| Mode | One-line value | Typical trigger |
+|------|-----------|------------|
+| `--file` | Understand file skeleton without full source reading, down to exact lines | Before taking over large module; narrow read scope in bug investigation |
+| `--who-imports` | Pre-change "blast list" of all callers | Must run before deleting funcs/changing signatures/renaming classes |
+| `--impact` | `0 upstream, 24 downstream` shows scope at a glance | Sprint estimation; decide local surgery vs global surgery |
+| `--hub-analysis` | Find true high-coupling core without guessing by directory names | Architecture review; technical debt prioritization |
+| `--summary` | Build global layered understanding in 5 seconds, more objective than README | First contact with project; identify cyclic-risk regions |
+
+---
+
+## Scenario Quick Reference
+
+| Your question now | Use |
+|-------------|--------|
+| What classes/methods are in this file, and at what lines | `--file` |
+| If I change this interface/delete func, which files must change | `--who-imports` |
+| How many modules are ultimately affected by this change | `--impact` |
+| How risky is this change (with git heat) | `--impact --git-stats` |
+| Which module is true high-coupling core | `--hub-analysis` |
+| Overall module distribution and layering | `--summary` |
+| Continuous refactoring, need impact chain after one change | `--who-imports` -> `--impact` |
+| Estimate workload for technical debt refactor | `--hub-analysis` -> `--impact` |
+
+---
+
+## Execution Rules
+
+**Rule 1: Skeleton before query**
+Before using `--impact` or `--who-imports` on a module, preferably run `--file` first to understand responsibilities and imports, reducing misinterpretation of query results.
+
+**Rule 2: git-stats is optional bonus, not hard blocker**
+If no `.git` or insufficient history, skip `git_detective.py` and query with AST only.
+
+**Rule 3: Path matching is flexible but verify**
+Path fragment matching is supported (e.g., `vision.py` can match `src/core/vision.py`). If result is `[NOT FOUND]`, run `--summary` first to confirm module path format in repo, then query again.
+
+**Rule 4: Present results directly; let numbers speak**
+`--impact` output `X upstream, Y downstream` is objective. Report it directly; do not replace with vague wording like "possibly large impact".