@haaaiawd/anws 2.2.6 → 2.4.0

package/templates_en/.agents/skills/nexus-query/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-query/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/output-contract/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: output-contract
+description: Load when persisting reports in this template bundle, running parallel child sessions, or aligning outputs across workflows. Holds shared on-disk spec and delegation loop; unrelated to craft-authoring (/craft scaffolds).
+---
+
+# Output contract and collaboration loop
+
+> If another skill or workflow repeats these bullets, replace with **one line pointing here** and keep only role- or step-specific deltas.
+
+## When to load
+
+- Authoring architecture / review / exploration Markdown that will land in the repo.
+- Parent session splits parallel children or path-sliced collaboration.
+- Verifying traceability, duplicate storytelling, or single-writer rules.
+
+## Shared spec contract
+
+- **Precise**: Verifiable statements must cite sources or `path:line` / section anchors; no unsourced strong claims.
+- **Evidence-backed**: Findings / evidence / recommendations must trace back to concrete inputs or retrieval results.
+- **Non-repetitive**: State each fact once; no duplicate narrative in summary vs body.
+- **No filler**: Ban vague boilerplate (“needs optimization”, “should watch”) without a clear subject.
+
+Normative blocks (CRITICAL, severity tables, gates, upstream/downstream contracts) **must not be deleted**; tightening targets execution chatter and repetitive storytelling only.
+
+## Delegation loop (parent ↔ child)
+
+1. **Parent session**: `TARGET_DIR`, round, final paths, merge order, **sole write** to normalized report paths.
+2. **Child session**: Bounded slice; same evidence rules as parent.
+3. **Handoff**: Child returns mergeable table structure + one-line verdict; parent dedupes, checks against spec, writes `07_*` / explore reports, then runs workflow **completion** at the end.
+
+Without delegation: single session runs the full workflow; parent still owns final persistence and consistency.
+
+## Parallelism and paths
+
+- At most **one active writer per managed path (or glob)** per batch; no repo-wide format passes outside authorized globs.
+- Child scopes must be **disjoint** by directory or topic; parent arbitrates conflicts.
+- Checklist phrasing aligned with `/genesis` lives in **`genesis.md`** “Sub-agent orchestration and handoff checklist” (same section title in EN trees).

package/templates_en/.agents/skills/report-template/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: report-template
+description: Synthesize all Probe-stage analysis (nexus-mapper, runtime-inspector) into a decision-ready system risk report.
+---
+
+# The Synthesizer's Manual
+
+> "Data is not information. Information is not knowledge. Knowledge is not wisdom." -- T.S. Eliot
+
+Your goal is to convert raw analysis into **wisdom architects can act on**.
+
+---
+
+## Mandatory Self-Correction
+
+> [!IMPORTANT]
+> Before generating the report, you **must** self-check:
+> 1. "Do build boundaries from nexus-mapper align with IPC boundaries from runtime-inspector?"
+> 2. "Do high-coupling file pairs from nexus-mapper cross build boundaries?"
+> 3. "Are missing components identified by nexus-mapper related to discovered risks?"
+> 4. "Is this report complete enough?"
+
+---
+
+## Quick Start
+
+1. **Read template (MANDATORY)**: Read `references/REPORT_TEMPLATE.md`. Your report **must** match this structure exactly.
+2. **Synthesize all findings**: Merge outputs from:
+   * `nexus-mapper` -> Build Roots, Topology, Coupling Pairs, Hotspots, Entities, Missing Components
+   * `runtime-inspector` -> IPC Surfaces, Contract Status
+3. **Draft report**: Organize with explicit logical connections.
+4. **Publish (CRITICAL)**: You **must** create `.anws/v{N}/00_PROBE_REPORT.md` and write the full report. **Do not** only print in chat. Ensure `.anws/v{N}/` exists.
+
+---
+
+## Completion Checklist
+
+Before moving to next phase, verify:
+- [ ] Output file created: `.anws/v{N}/00_PROBE_REPORT.md`
+- [ ] Includes: System Fingerprint, Component Map, Risk Matrix, Feature Landing Guide
+- [ ] User has confirmed findings
+
+---
+
+## Synthesis Ritual
+
+### 1. Executive Summary
+* **Elevator pitch**: Describe system health in 30 seconds.
+* **Focus points**: technical debt, key risks, reliability.
+
+### 2. Dark Matter Detection
+* Do not only list what exists. **List what is missing**.
+* Checklist: logs? error handling? CI/CD? secret management? version handshake?
+
+### 3. Cross-Verification
+* **nexus-mapper** says "Workspace managed uniformly"?
+* **nexus-mapper** says "High coupling crosses build roots"?
+* **Conclusion**: detect hidden logical coupling -> **refactor target**.
+
+### 4. Human Checkpoint
+* Force user confirmation: "Is this report complete?"
+* **Do not enter Blueprint before this report is signed off**.
+
+---
+
+## Master Rules
+
+1. **No hallucination**: Every claim must link to source files.
+2. **Brutal honesty**: Be direct. If it's a mess, say it's a mess.
+3. **Action-oriented**: Every listed issue must imply a path (refactor/rewrite/retain).
+
+---
+
+## Toolbox
+
+* `references/REPORT_TEMPLATE.md`: main report template.
+
+---
+
+## Consumers
+
+Direct consumer of this report in `/blueprint` phase:
+* **System Architect**: depends on your risk list to design mitigation strategy.
+
+Your analysis quality **directly determines** design quality in the next phase.