@haaaiawd/anws 2.3.0 → 2.4.1

package/templates_en/.agents/skills/nexus-mapper/references/output-schema.md

@@ -0,0 +1,311 @@
+# Output Schema Specification
+
+> **EMIT phase hard gate**: This file is forcibly triggered for reading by EMIT phase gate of `probe-protocol.md`,
+> must complete reading this file before writing any `.nexus-map/` file.
+> All schemas in this document are corrected based on actual runtime output, consistent with current script version.
+
+---
+
+## raw/ast_nodes.json (extract_ast.py output)
+
+### Top-level structure
+
+```json
+{
+  "languages": ["cpp", "python"],
+  "stats": {
+    "total_files": 101,
+    "total_lines": 23184,
+    "parse_errors": 0,
+    "truncated": true,
+    "truncated_nodes": 298,
+    "supported_file_counts": {"python": 101},
+    "languages_with_structural_queries": ["python", "javascript", "typescript"],
+    "languages_with_custom_queries": ["gdscript"],
+    "module_only_file_counts": {"vue": 12},
+    "known_unsupported_file_counts": {"customdsl": 24},
+    "configured_but_unavailable_file_counts": {"templ": 6},
+    "custom_language_config_paths": ["/custom/path/to/language-config.json"]
+  },
+  "warnings": [
+    "custom language configuration loaded: /custom/path/to/language-config.json",
+    "some languages were parsed with module-only coverage because no structural query template is bundled: vue (12 files)",
+    "known unsupported languages present; downstream outputs must mark inferred sections explicitly: customdsl (24 files)",
+    "some configured languages were detected in source files but no parser could be loaded: templ (6 files)"
+  ],
+  "nodes": [...],
+  "edges": [...]
+}
+```
+
+### Module node
+
+```json
+{
+  "id": "src.nexus.application.weaving.treesitter_parser",
+  "type": "Module",
+  "label": "treesitter_parser",
+  "path": "src/nexus/application/weaving/treesitter_parser.py",
+  "lines": 320,
+  "lang": "python"
+}
+```
+
+### Class node
+
+```json
+{
+  "id": "src.nexus.application.weaving.treesitter_parser.TreeSitterParser",
+  "type": "Class",
+  "label": "TreeSitterParser",
+  "path": "src/nexus/application/weaving/treesitter_parser.py",
+  "parent": "src.nexus.application.weaving.treesitter_parser",
+  "start_line": 15,
+  "end_line": 287
+}
+```
+
+### Edge
+
+```json
+{
+  "source": "src.nexus.infrastructure",
+  "target": "src.nexus.infrastructure.db_client",
+  "type": "contains"
+}
+```
+
+**Edge types**: `contains` (module→class, class→method) / `imports` (import statement parsing)
+
+### warnings field
+
+`warnings` is optional array, used to expose downgrade information that won't cause PROFILE failure but affects downstream credibility, for example:
+
+- grammar loadable, but currently only Module-level coverage
+- Known but unsupported languages exist
+- AST truncated
+- Some parsers unavailable
+
+### Coverage layering fields
+
+
+| Field                                    | Meaning                                                                                            |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `supported_file_counts`                  | Files successfully entering AST flow (including full structural coverage and module-only coverage) |
+| `languages_with_structural_queries`      | Languages covered by current bundled query templates                                               |
+| `languages_with_custom_queries`          | Languages where queries added or overridden via `--add-query` or `--language-config`               |
+| `module_only_file_counts`                | Languages where grammar loadable, but no structural query currently, only produce Module nodes     |
+| `known_unsupported_file_counts`          | Languages known to exist but completely not entering AST flow                                      |
+| `configured_but_unavailable_file_counts` | Languages agent explicitly requested support for, but current environment has no available parser  |
+| `custom_language_config_paths`           | Paths of explicit language config files actually loaded this time; empty in pure CLI mode          |
+
+
+---
+
+## raw/git_stats.json (git_detective.py output)
+
+```json
+{
+  "analysis_period_days": 90,
+  "stats": {
+    "total_commits": 42,
+    "total_authors": 1
+  },
+  "hotspots": [
+    {"path": "src/nexus/tasks/analysis_tasks.py", "changes": 21, "risk": "high"}
+  ],
+  "coupling_pairs": [
+    {"file_a": "...", "file_b": "...", "co_changes": 5, "coupling_score": 0.71}
+  ]
+}
+```
+
+**Risk threshold**: `changes < 5` → `low` / `5–15` → `medium` / `> 15` → `high`
+
+---
+
+## Generated Markdown file headers
+
+Headers of `INDEX.md`, `arch/*.md`, `concepts/domains.md`, `hotspots/git_forensics.md` must at minimum contain:
+
+```markdown
+> generated_by: nexus-mapper v2
+> verified_at: 2026-03-07
+> provenance: AST-backed except where explicitly marked inferred
+```
+
+If language downgrade or manual inference exists, `provenance` must be expanded:
+
+```markdown
+> provenance: AST-backed for Python; some custom DSL files were detected but not parsed by bundled AST tooling, so the affected dependency notes below are inferred from file tree and manual inspection.
+```
+
+---
+
+## concepts/concept_model.json — Schema V1
+
+Schema V1 human-readable name field only has `label`, do not introduce additional `title`; if `title` appears, treat as non-standard field, should delete.
+
+```json
+{
+  "$schema": "nexus-mapper/concept-model/v1",
+  "generated_at": "2026-03-05T15:00:00Z",
+  "repo_path": "/absolute/path/to/repo",
+  "generator": "nexus-mapper v2",
+  "nodes": [
+    {
+      "id": "nexus.ast-extractor",
+      "type": "System",
+      "label": "AST Extractor",
+      "responsibility": "Use Tree-sitter to parse Python repo, extract module/class/function nodes and import relationships, output machine-readable JSON",
+      "implementation_status": "implemented",
+      "code_path": "src/nexus/application/weaving/",
+      "evidence_path": null,
+      "evidence_gap": null,
+      "tech_stack": ["tree-sitter", "python"],
+      "related_reqs": ["REQ-101"],
+      "complexity": "medium",
+      "hotspot": true
+    }
+  ],
+  "edges": [
+    {
+      "source": "nexus.ast-extractor",
+      "target": "nexus.task-dispatcher",
+      "type": "depends_on",
+      "description": "Optional description"
+    }
+  ],
+  "metadata": {
+    "total_files": 101,
+    "total_lines": 23184,
+    "languages": ["python"],
+    "git_commits_analyzed": 42,
+    "analysis_days": 90
+  }
+}
+```
+
+### Node field validation rules
+
+
+| Field                   | Required             | Triggers `[!ERROR]` situation                                                               |
+| ----------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
+| `id`                    | Yes                  | Global duplicate; contains uppercase letters or spaces (must be kebab-case lowercase)       |
+| `type`                  | Yes                  | Not in enum `System / Domain / Module / Class / Function`                                   |
+| `label`                 | Yes                  | Empty string                                                                                |
+| `title`                 | No                   | Schema V1 does not define this field; if written, treat as extra field                      |
+| `responsibility`        | Yes                  | Too vague to verify; character count < 10 or > 120                                          |
+| `implementation_status` | Yes                  | Not in enum `implemented / planned / inferred`                                              |
+| `code_path`             | Conditional required | `implementation_status=implemented` but empty; or path does not actually exist in repo      |
+| `evidence_path`         | Conditional required | `implementation_status=planned/inferred` but empty; or path does not actually exist in repo |
+| `evidence_gap`          | Conditional required | `implementation_status=planned/inferred` but empty                                          |
+
+
+### Node status expression specification
+
+**Implemented node**
+
+```json
+{
+  "implementation_status": "implemented",
+  "code_path": "src/server/",
+  "evidence_path": null,
+  "evidence_gap": null
+}
+```
+
+**Planned node**
+
+```json
+{
+  "implementation_status": "planned",
+  "code_path": null,
+  "evidence_path": "docs/architecture.md",
+  "evidence_gap": "Design document mentions Monarch/Executor, but src/agents/monarch/ not found in repo"
+}
+```
+
+**Inferred node**
+
+```json
+{
+  "implementation_status": "inferred",
+  "code_path": null,
+  "evidence_path": "docs/architecture.md",
+  "evidence_gap": "Repo contains currently unsupported DSL files; this boundary comes from file tree and manual reading"
+}
+```
+
+---
+
+## query_graph.py output format reference (stdout, not written to file)
+
+### --file
+
+```
+=== <file_path> ===
+Module: <module_id> (<lines> lines, <lang>)
+
+Classes:
+  <ClassName> (L<start>-L<end>)
+    ├─ <method_name> (L<start>-L<end>)
+    └─ <method_name> (L<start>-L<end>)
+
+Top-level Functions:
+  <func_name> (L<start>-L<end>)
+
+Imports:
+  → <internal_module> (<path>)
+  → <external_package> (external)
+```
+
+### --who-imports
+
+```
+=== Who imports <module>? ===
+Imported by N module(s):
+  ← <module_id> (<path>)
+```
+
+### --impact
+
+```
+=== Impact radius: <file_path> ===
+
+Depends on (this file imports):
+  → <module_id> (<path>)
+
+Depended by (other files import this):
+  ← <module_id> (<path>)
+
+Impact summary: N upstream dependencies, M downstream dependents
+
+# Following only output when --git-stats passed and that file has hotspot/coupling data
+Git risk: high (N changes in 90 days)
+Coupled files (co-change):
+  - <peer_path> (coupling: 0.XX, N co-changes)
+```
+
+### --hub-analysis
+
+```
+=== Hub Analysis ===
+
+Top fan-in (most imported by others):
+  1. <module_id> — imported by N module(s)  [<path>]
+
+Top fan-out (imports most others):
+  1. <module_id> — imports N internal module(s)  [<path>]
+```
+
+### --summary
+
+```
+=== Directory Summary ===
+
+<dir>/ (N modules, N classes, N functions, N lines)
+  Key classes: ClassA, ClassB, ...
+  Key imports from: <other_dir>, ...
+```
+

package/templates_en/.agents/skills/nexus-mapper/references/probe-protocol.md

@@ -0,0 +1,246 @@
+# PROBE Protocol — Detailed Steps for Each Phase
+
+> This file is the execution blueprint for SKILL.md. After Skill activation, **first step** is to read this file completely in one go.
+> Before EMIT, also need to read `references/output-schema.md` (Schema too specific, placed separately to save context during activation).
+> For non-standard language support, see `references/language-customization.md` (as needed, not gated).
+
+---
+
+## P — PROFILE Phase
+
+**Pre-validation**
+1. Confirm `$repo_path` directory exists
+2. Check whether `$repo_path/.git` exists
+   - Exists: execute git hotspot analysis
+   - Does not exist: record `git analysis skipped`, continue with AST and file tree exploration
+
+**Execution steps**
+
+```bash
+# Step 1: Run AST extractor (simultaneously generate filtered file tree)
+python $SKILL_DIR/scripts/extract_ast.py $repo_path [--max-nodes 500] \
+  --file-tree-out .nexus-map/raw/file_tree.txt \
+  > $repo_path/.nexus-map/raw/ast_nodes.json
+
+# If repo contains languages not covered by built-in, supplement support via command line args
+python $SKILL_DIR/scripts/extract_ast.py $repo_path [--max-nodes 500] \
+  --add-extension .templ=templ \
+  --add-query templ struct "(component_declaration name: (identifier) @class.name) @class.def" \
+  --file-tree-out .nexus-map/raw/file_tree.txt \
+  > $repo_path/.nexus-map/raw/ast_nodes.json
+
+# Or use explicit JSON config file (when configuration complex, see references/language-customization.md for details)
+python $SKILL_DIR/scripts/extract_ast.py $repo_path [--max-nodes 500] \
+  --language-config /custom/path/to/language-config.json \
+  --file-tree-out .nexus-map/raw/file_tree.txt \
+  > $repo_path/.nexus-map/raw/ast_nodes.json
+
+# Step 2: Run git hotspot analysis (only when .git exists)
+python $SKILL_DIR/scripts/git_detective.py $repo_path --days 90 \
+  > $repo_path/.nexus-map/raw/git_stats.json
+```
+
+> `$SKILL_DIR` is this Skill's installation path (`.agents/skills/nexus-mapper` or independent repo path).
+> `$repo_path` is absolute path to target repo.
+> `extract_ast.py --file-tree-out` by default excludes `.git/`, `.nexus-map/`, `node_modules/`, `__pycache__/`, `.venv/`, `dist/`, `build/` and other noise directories and files.
+
+**Completion check (any failure → stop, do not enter REASON)**
+- [ ] `raw/ast_nodes.json` written (empty `nodes` list is also normal downgrade)
+- [ ] `raw/file_tree.txt` not empty
+- [ ] If git history exists: `raw/git_stats.json` not empty, contains `hotspots` field
+- [ ] If git history does not exist: explicitly recorded this is a no-git downgrade exploration
+- [ ] If `ast_nodes.json.stats.known_unsupported_file_counts` not empty: recorded language coverage downgrade
+- [ ] If `ast_nodes.json.stats.module_only_file_counts` not empty: recorded which languages only have Module-level coverage
+- [ ] If `ast_nodes.json.stats.configured_but_unavailable_file_counts` not empty: recorded this part as uncovered
+
+---
+
+## R — REASON Phase
+
+**Boundary scenario pre-check** (before reading project files, go through following checklist first, if any item hit, adjust execution strategy)
+
+| Scenario                          | Identification method                    | Handling                                                                                     |
+| --------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------------------- |
+| New repo without git history      | `.git` exists but only 1 commit         | Skip `git_detective.py`, write `git analysis skipped: insufficient history` in output       |
+| Non-git repo                      | `.git` does not exist                   | Skip `git_detective.py`, final output mark `hotspots skipped: no git metadata`              |
+| Large Monorepo (>1000 files)      | `stats.truncated=true`                   | Inform user to use `--max-nodes 200`; `truncated=true` is expected behavior                  |
+| Git history too long (>3000 commits) | Analysis slow / git data too large     | Use `--days 30` instead of default 90 days                                                 |
+| Project without README            | No README in root directory             | Skip directly to `pyproject.toml` / `package.json`; hypothesis log note evidence gap          |
+| Repo with roadmap/Sprint status   | README/TASKS contains time-sensitive status | Allow summary, must attach `verified_at` and source doc path; prohibited to write undated status as current fact |
+| Truncation behavior (truncated=true) | `stats.truncated_nodes > 0`         | Function nodes discarded, will not generate `raw/functions.json`; can produce complete output based on Module/Class nodes |
+
+> [!DEVIATION]
+> **Known implementation deviation**: Truncated Function nodes are **directly discarded**, **will not generate** `raw/functions.json`.
+> If any document describes truncated nodes written to separate file, actual behavior takes precedence.
+
+**Multi-language coverage layering**
+
+| Status                   | Identification field                                 | EMIT requirement                                                    |
+| ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------- |
+| Full structural coverage | `languages_with_structural_queries`                  | Normal output                                                       |
+| Module-only coverage     | `module_only_file_counts`                            | Must not describe as "full AST coverage"; fine-grained conclusions must be conservative |
+| Configured but parser unavailable | `configured_but_unavailable_file_counts` | Treat as uncovered, not module-only; dependency conclusions only write `inferred` |
+| Completely not integrated | `known_unsupported_file_counts`                     | `INDEX.md` mark downgrade; related regions add `inferred/manual inspection` |
+
+**Reading strategy (priority from high to low)**
+1. `README.md` / `README.rst` — project overall description
+2. `pyproject.toml` / `package.json` / `pom.xml` — tech stack and dependencies
+3. Main entry files (`main.py`, `index.ts`, `Application.java`)
+4. `raw/file_tree.txt` — directory structure awareness
+5. `raw/git_stats.json` hotspots Top 5 — most active files (only when git data available)
+6. Test directory — establish static test surface, no need to run tests
+
+**Execution requirements**
+- Perform deep thinking, gradually deduce key decision points sufficient to support conclusions, usually 3-5
+- Identify repo's main System-level nodes, usually 1-5; do not split pure technical details into independent systems just to pad numbers
+- **[Recommended]** Run hub-analysis to validate core system hypothesis with fan-in/fan-out data:
+  ```bash
+  python $SKILL_DIR/scripts/query_graph.py $repo_path/.nexus-map/raw/ast_nodes.json --hub-analysis
+  ```
+
+**Recording format** (working memory, not write file)
+```
+[REASON LOG]
+- System A: inferred responsibility=X, implementation_status=implemented, code_path=Y (confidence: high/medium/low)
+- System B: inferred responsibility=X, implementation_status=planned, evidence_path=Y (confidence: high/medium/low)
+- Evidence gap: Z directory attribution lacks direct evidence (will challenge in OBJECT)
+```
+
+---
+
+## O — OBJECT Phase
+
+**Why challenge needed**: System hypotheses established by first intuition have three typical biases — directory name ≠ responsibility, git hotspots reveal true core, import direction reveals hierarchy errors. Three dimensions (below) systematically cover these three bias types.
+
+**Challenge protocol** — propose minimum set of high-value challenges sufficient to challenge current hypothesis, usually 1-3, each with evidence clues
+
+Challenge point format:
+```
+Q{N}: [specific contradiction or suspicious point]
+Evidence clue: [where contradiction found — file path/line number/git data]
+Verification plan: [how to verify in BENCHMARK phase]
+```
+
+Unqualified challenges (prohibited to submit):
+```
+Q1: My grasp of system structure is not solid enough
+Q2: xxx directory responsibilities have no direct evidence yet
+```
+Problem is not wording, but lack of code citation and no executable verification plan.
+
+Qualified example:
+```
+Q1: git_stats shows tasks/analysis_tasks.py changed 21 times (high risk),
+    but REASON thinks orchestration entry is evolution/detective_loop.py.
+    Contradiction: If detective_loop is entry, why is analysis_tasks hotter?
+    Evidence clue: raw/git_stats.json hotspots[0]
+    Verification plan: view tasks/analysis_tasks.py class definition + import tree
+```
+
+**Three-dimensional challenge framework** (corresponding to Structure / Evolution / Dependency)
+
+| Dimension   | Data source                                      | High-value challenge pattern                                                                       |
+| ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Structure   | `raw/file_tree.txt`, ast edges(`contains`)       | Business-named files appear in hypothesized "infrastructure layer" directory; multiple System files in same `utils/` (boundary blurry) |
+| Evolution   | `raw/git_stats.json` hotspots + coupling_pairs   | Hotspot top not within hypothesized "core system"; coupling_score > 0.7 file pairs belong to different Systems (boundary wrong) |
+| Dependency  | ast edges(`imports`)                            | Hypothesized lower layer module imports upper layer module (circular dependency/layering error); import direction opposite to hypothesis |
+
+**Challenge grading**
+
+| Level     | Definition                                                     | BENCHMARK priority        |
+| --------- | --------------------------------------------------------------- | :-----------------------: |
+| Critical  | Hypothesized system boundaries completely wrong, `code_path` should point to completely different location | Verify immediately, do not enter EMIT before verification |
+| High      | Core system's `code_path` may be wrong or missed important subdirectories | BENCHMARK first batch     |
+| Medium    | Subdirectory responsibility division vague, may affect `responsibility` accuracy | BENCHMARK second batch    |
+
+> If evidence only supports Medium, keep Medium. At least one challenge must truly potentially change system boundary, main entry, or dependency direction.
+
+**Three-dimensional execution checklist**
+- [ ] Structure: Does file_tree.txt have files/directories that cannot match hypothesized systems?
+- [ ] Structure: Do cross-system `utils/`/`common/` directories exist with ambiguous zones?
+- [ ] Evolution: When git data available, do hotspot front ranks support "core system" judgment?
+- [ ] Evolution: Are there strong coupling pairs across hypothesized system boundaries in coupling_pairs (score > 0.5)?
+- [ ] Dependency: Are there import edges violating hypothesized layering direction (lower layer imports upper layer)?
+- [ ] Dependency: Are any System's import directions opposite to hypothesized "dependent-dependee" relationship?
+
+---
+
+## B — BENCHMARK Phase
+
+**Execute verification for each challenge point**
+1. Use `grep_search` / `view_file` to find specific evidence
+2. **[Recommended]** Use `query_graph.py --impact` to view target file's real upstream/downstream dependencies:
+   ```bash
+   python $SKILL_DIR/scripts/query_graph.py $repo_path/.nexus-map/raw/ast_nodes.json \
+     --impact <target file> --git-stats $repo_path/.nexus-map/raw/git_stats.json
+   ```
+3. Judge result:
+   - Challenge valid → correct node's `code_path` or `responsibility`, mark "corrected" in LOG
+   - Challenge invalid → confirm original hypothesis, mark "verified"
+
+**Global node validation (execute for all System nodes one by one)**
+- [ ] `implemented` node's `code_path` actually exists in repo
+- [ ] `planned/inferred` nodes do not fake `code_path`, use `evidence_path + evidence_gap` instead
+- [ ] Each `planned/inferred` node's `evidence_path` actually exists in repo
+- [ ] `responsibility` expression clear, specific; if evidence insufficient, explicitly record evidence gap
+- [ ] Node `id` globally unique, kebab-case, all lowercase
+
+> If key system completely identified incorrectly → allowed to return to REASON to rebuild model, and re-execute OBJECT.
+
+---
+
+## E — EMIT Phase
+
+> [!IMPORTANT]
+> **Phase gate**: Before writing any file, must first read:
+> `references/output-schema.md`
+> Writing without reading that file → produced JSON/Markdown structure cannot pass Schema validation, considered invalid.
+
+**Idempotency check (must do before writing)**
+
+| Check result                             | Handling                                              |
+| ---------------------------------------- | ----------------------------------------------------- |
+| `.nexus-map/` does not exist             | Continue directly                                    |
+| `.nexus-map/` exists and `INDEX.md` valid | Ask user: "Detected existing analysis results, overwrite? [y/n]" |
+| `.nexus-map/` exists but files incomplete | "Detected incomplete analysis, will regenerate", continue |
+
+**[Recommended] Get structure summary before writing**
+```bash
+python $SKILL_DIR/scripts/query_graph.py $repo_path/.nexus-map/raw/ast_nodes.json --summary
+```
+
+**Writing order (first write `.tmp/`, after all successful move all together)**
+```
+1. .nexus-map/.tmp/concepts/concept_model.json   ← Schema V1
+2. .nexus-map/.tmp/INDEX.md                       ← L0 summary, < 2000 tokens
+3. .nexus-map/.tmp/arch/systems.md                ← each System boundary
+4. .nexus-map/.tmp/arch/dependencies.md           ← Mermaid dependency graph
+5. .nexus-map/.tmp/arch/test_coverage.md          ← static test surface and evidence gaps
+6. .nexus-map/.tmp/concepts/domains.md            ← Domain concept explanation
+7. .nexus-map/.tmp/hotspots/git_forensics.md      ← Git hotspot summary
+```
+
+All write successful → move `.tmp/` contents to `.nexus-map/` → delete `.tmp/`
+
+**INDEX.md writing requirements**
+- token count < 2000, rewrite if exceeded
+- Conclusions specific, do not use vague words to dodge; when evidence insufficient, explicitly write `evidence gap` or `unknown`
+- **Must include "Operation Guide" hard routing block defined in SKILL.md Rule 4**
+
+**Each Markdown file header must at minimum contain**
+```markdown
+> generated_by: nexus-mapper v2
+> verified_at: 2026-03-07
+> provenance: AST-backed except where explicitly marked inferred
+```
+
+**Edge merging protocol (execute before writing concept_model.json)**
+1. Import edges from `raw/ast_nodes.json` (`imports`/`contains`, machine layer precise)
+2. Append semantic edges inferred in BENCHMARK phase (`depends_on`/`calls`)
+3. Deduplicate: keep one edge for same `(source, target, type)` triplet
+
+**Completion validation**
+- [ ] `INDEX.md` exists, conclusions specific and honest about evidence gaps, < 2000 tokens, contains hard routing block
+- [ ] `implemented` nodes in `concept_model.json` all have verified `code_path`
+- [ ] `arch/dependencies.md` contains >= 1 Mermaid graph
+- [ ] `arch/test_coverage.md` explains static test surface, and explicitly states evidence gap of not running tests