java-codebase-rag 0.2.0__tar.gz → 0.2.2__tar.gz

{java_codebase_rag-0.2.0/java_codebase_rag.egg-info → java_codebase_rag-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.2.0
+Version: 0.2.2
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: cocoindex[lancedb]<2,>=1.0.0a43
 Requires-Dist: kuzu<0.12,>=0.11.3
 Requires-Dist: lancedb<0.31,>=0.25.3
 Requires-Dist: mcp<2,>=1.27.0
@@ -26,6 +27,7 @@ Requires-Dist: pathspec<2,>=1.0.4
 Requires-Dist: pyarrow<24,>=23.0.1
 Requires-Dist: PyYAML<7,>=6.0.3
 Requires-Dist: sentence-transformers<6,>=5.4.0
+Requires-Dist: transformers<=5.5.3,>=4.48.3
 Requires-Dist: tree-sitter<0.26,>=0.25.2
 Requires-Dist: tree-sitter-java<0.24,>=0.23.5
 Requires-Dist: unidiff<1,>=0.7.3
@@ -50,6 +52,24 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 ---
 
+## Why this exists
+
+Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
+
+- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (Kuzu property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `DECLARES_ROUTE`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+
+- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `CLIENT`, `PRODUCER`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
+
+- **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
+
+- **Cross-service resolution + system-level navigation.** `HTTP_CALLS` and `ASYNC_CALLS` edges connect Clients and Producers in one microservice to Routes and Handlers in another, resolved at index time from URL/topic strings + Spring `@FeignClient` / `RestTemplate` conventions. `/who-hits-route`, `/trace-request-flow`, and `/impact-of` use these to answer questions a single-service tool fundamentally can't — "who calls this REST endpoint from outside this service", "trace this Kafka message end-to-end", "if I change this DTO, which services break".
+
+- **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
+
+The rest of this README is the install, walkthrough, and tool cheat sheet for putting that to work.
+
+---
+
 ## Install
 
 ```bash
@@ -57,6 +77,7 @@ pip install java-codebase-rag
 ```
 
 Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
+The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase`.
 
 > **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
 
@@ -132,9 +153,9 @@ See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (
 
 Pick **one** of two options (not both — they cover the same navigation intents):
 
-1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and inline slash-style aliases (`/callers`, `/callees`, `/routes`, etc.) as prompt templates. Self-contained — no external file dependencies.
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
 
-2. **[`skills/`](./skills/)** (for hosts with skill discovery) — 15 shipped `SKILL.md` files. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), the same navigation intents are available as discoverable `/` commands. Tier 1 = deterministic MCP chains (`/callers`, `/callees`, `/routes`, `/controllers`, `/clients`, `/producers`, `/handlers`, `/who-hits-route`, `/implements`, `/injects`, `/nl`). Tier 2 = bounded workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). See [`skills/README.md`](./skills/README.md) for the full index.
+2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
 
 Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
 
@@ -154,7 +175,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skills). Navigation skills in [`skills/`](./skills/) wrap the MCP tools into deterministic chains (Tier 1) and bounded workflows (Tier 2). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -197,7 +218,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | 15 navigation and workflow skills for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | Single `/explore-codebase` skill — complete MCP operating manual for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
@@ -214,7 +235,7 @@ python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt
 ```
 
-The `cocoindex` package is **only** needed for lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation work without it.
+The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.
 
 The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
 

{java_codebase_rag-0.2.0 → java_codebase_rag-0.2.2}/README.md

@@ -17,6 +17,24 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 ---
 
+## Why this exists
+
+Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
+
+- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (Kuzu property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `DECLARES_ROUTE`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+
+- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `CLIENT`, `PRODUCER`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
+
+- **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
+
+- **Cross-service resolution + system-level navigation.** `HTTP_CALLS` and `ASYNC_CALLS` edges connect Clients and Producers in one microservice to Routes and Handlers in another, resolved at index time from URL/topic strings + Spring `@FeignClient` / `RestTemplate` conventions. `/who-hits-route`, `/trace-request-flow`, and `/impact-of` use these to answer questions a single-service tool fundamentally can't — "who calls this REST endpoint from outside this service", "trace this Kafka message end-to-end", "if I change this DTO, which services break".
+
+- **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
+
+The rest of this README is the install, walkthrough, and tool cheat sheet for putting that to work.
+
+---
+
 ## Install
 
 ```bash
@@ -24,6 +42,7 @@ pip install java-codebase-rag
 ```
 
 Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
+The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase`.
 
 > **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
 
@@ -99,9 +118,9 @@ See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (
 
 Pick **one** of two options (not both — they cover the same navigation intents):
 
-1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and inline slash-style aliases (`/callers`, `/callees`, `/routes`, etc.) as prompt templates. Self-contained — no external file dependencies.
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
 
-2. **[`skills/`](./skills/)** (for hosts with skill discovery) — 15 shipped `SKILL.md` files. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), the same navigation intents are available as discoverable `/` commands. Tier 1 = deterministic MCP chains (`/callers`, `/callees`, `/routes`, `/controllers`, `/clients`, `/producers`, `/handlers`, `/who-hits-route`, `/implements`, `/injects`, `/nl`). Tier 2 = bounded workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). See [`skills/README.md`](./skills/README.md) for the full index.
+2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
 
 Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
 
@@ -121,7 +140,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skills). Navigation skills in [`skills/`](./skills/) wrap the MCP tools into deterministic chains (Tier 1) and bounded workflows (Tier 2). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -164,7 +183,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | 15 navigation and workflow skills for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | Single `/explore-codebase` skill — complete MCP operating manual for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
@@ -181,7 +200,7 @@ python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt
 ```
 
-The `cocoindex` package is **only** needed for lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation work without it.
+The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.
 
 The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
 

{java_codebase_rag-0.2.0 → java_codebase_rag-0.2.2/java_codebase_rag.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.2.0
+Version: 0.2.2
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -18,6 +18,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: cocoindex[lancedb]<2,>=1.0.0a43
 Requires-Dist: kuzu<0.12,>=0.11.3
 Requires-Dist: lancedb<0.31,>=0.25.3
 Requires-Dist: mcp<2,>=1.27.0
@@ -26,6 +27,7 @@ Requires-Dist: pathspec<2,>=1.0.4
 Requires-Dist: pyarrow<24,>=23.0.1
 Requires-Dist: PyYAML<7,>=6.0.3
 Requires-Dist: sentence-transformers<6,>=5.4.0
+Requires-Dist: transformers<=5.5.3,>=4.48.3
 Requires-Dist: tree-sitter<0.26,>=0.25.2
 Requires-Dist: tree-sitter-java<0.24,>=0.23.5
 Requires-Dist: unidiff<1,>=0.7.3
@@ -50,6 +52,24 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 ---
 
+## Why this exists
+
+Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
+
+- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (Kuzu property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `DECLARES_ROUTE`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+
+- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `CLIENT`, `PRODUCER`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
+
+- **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
+
+- **Cross-service resolution + system-level navigation.** `HTTP_CALLS` and `ASYNC_CALLS` edges connect Clients and Producers in one microservice to Routes and Handlers in another, resolved at index time from URL/topic strings + Spring `@FeignClient` / `RestTemplate` conventions. `/who-hits-route`, `/trace-request-flow`, and `/impact-of` use these to answer questions a single-service tool fundamentally can't — "who calls this REST endpoint from outside this service", "trace this Kafka message end-to-end", "if I change this DTO, which services break".
+
+- **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
+
+The rest of this README is the install, walkthrough, and tool cheat sheet for putting that to work.
+
+---
+
 ## Install
 
 ```bash
@@ -57,6 +77,7 @@ pip install java-codebase-rag
 ```
 
 Python **3.11+** required. After install, `java-codebase-rag --help` should print the CLI groups.
+The package includes the CocoIndex lifecycle dependency used by `init`, `increment`, `reprocess`, and `erase`.
 
 > **Stability disclaimer.** This package does **not** promise backward compatibility. MCP tool contracts, env vars, Lance/Kuzu schemas, config files, and Python APIs may change without a deprecation period. Track `main` and rebuild indexes when ontology or embedding settings change.
 
@@ -132,9 +153,9 @@ See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` (
 
 Pick **one** of two options (not both — they cover the same navigation intents):
 
-1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and inline slash-style aliases (`/callers`, `/callees`, `/routes`, etc.) as prompt templates. Self-contained — no external file dependencies.
+1. **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** (recommended for most) — standalone MCP operating manual. Copy-paste the `BEGIN`/`END` block into your project's `QWEN.md`, `CLAUDE.md`, or `AGENTS.md`. Contains: five-tool reference, `NodeFilter` / edge taxonomy, ontology glossary, recovery playbook, and navigation patterns. Self-contained — no external file dependencies.
 
-2. **[`skills/`](./skills/)** (for hosts with skill discovery) — 15 shipped `SKILL.md` files. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), the same navigation intents are available as discoverable `/` commands. Tier 1 = deterministic MCP chains (`/callers`, `/callees`, `/routes`, `/controllers`, `/clients`, `/producers`, `/handlers`, `/who-hits-route`, `/implements`, `/injects`, `/nl`). Tier 2 = bounded workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). See [`skills/README.md`](./skills/README.md) for the full index.
+2. **[`/explore-codebase`](./skills/explore-codebase/SKILL.md)** (for hosts with skill discovery) — single self-contained skill with the complete operating manual. If your MCP host supports skill discovery (Claude Code, Qwen Code, Cursor), load `/explore-codebase` to get the full tool reference, edge taxonomy, decision tree, and recovery playbook in one shot.
 
 Also: **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project.
 
@@ -154,7 +175,7 @@ Full schemas, `NodeFilter` / `EdgeFilter` semantics, and the hints contract live
 
 ### Three-layer architecture
 
-Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skills). Navigation skills in [`skills/`](./skills/) wrap the MCP tools into deterministic chains (Tier 1) and bounded workflows (Tier 2). See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
+Layer 1 (storage) → Layer 2 (5 MCP tools) → Layer 3 (skill). The [`/explore-codebase`](./skills/explore-codebase/SKILL.md) skill provides the full operating manual for Layer 2. See the [architecture diagram in `skills/README.md`](./skills/README.md#three-layer-architecture).
 
 ---
 
@@ -197,7 +218,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. |
 | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. |
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
-| [`skills/`](./skills/) | 15 navigation and workflow skills for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
+| [`skills/`](./skills/) | Single `/explore-codebase` skill — complete MCP operating manual for hosts with skill discovery (alternative to copy-pasting AGENT-GUIDE). See [`skills/README.md`](./skills/README.md). |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
 | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
 | [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). |
@@ -214,7 +235,7 @@ python3 -m venv .venv
 .venv/bin/pip install -r requirements.txt
 ```
 
-The `cocoindex` package is **only** needed for lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation work without it.
+The `cocoindex` package powers lifecycle commands that run the indexer (`init`, `increment`, `reprocess`, `erase`). Search and MCP navigation do not invoke it directly.
 
 The default embedding model is `sentence-transformers/all-MiniLM-L6-v2` (downloaded on first `init`). Override via the `EMBEDDING_MODEL` env var — see [`docs/CONFIGURATION.md` §1](./docs/CONFIGURATION.md#1-environment-variables).
 

{java_codebase_rag-0.2.0 → java_codebase_rag-0.2.2}/java_codebase_rag.egg-info/SOURCES.txt

@@ -61,6 +61,7 @@ tests/test_mcp_v2.py
 tests/test_mcp_v2_compose.py
 tests/test_meta_chain_core.py
 tests/test_outgoing_call_extraction.py
+tests/test_packaging_metadata.py
 tests/test_path_filtering.py
 tests/test_pr_analysis.py
 tests/test_resolve_routes_messaging_layer_c.py

{java_codebase_rag-0.2.0 → java_codebase_rag-0.2.2}/java_codebase_rag.egg-info/requires.txt

@@ -1,3 +1,4 @@
+cocoindex[lancedb]<2,>=1.0.0a43
 kuzu<0.12,>=0.11.3
 lancedb<0.31,>=0.25.3
 mcp<2,>=1.27.0
@@ -6,6 +7,7 @@ pathspec<2,>=1.0.4
 pyarrow<24,>=23.0.1
 PyYAML<7,>=6.0.3
 sentence-transformers<6,>=5.4.0
+transformers<=5.5.3,>=4.48.3
 tree-sitter<0.26,>=0.25.2
 tree-sitter-java<0.24,>=0.23.5
 unidiff<1,>=0.7.3

{java_codebase_rag-0.2.0 → java_codebase_rag-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "java-codebase-rag"
-version = "0.2.0"
+version = "0.2.2"
 description = "MCP server for semantic + structural search over Java codebases"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,6 +23,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
+    "cocoindex[lancedb]>=1.0.0a43,<2",
     "kuzu>=0.11.3,<0.12",
     "lancedb>=0.25.3,<0.31",
     "mcp>=1.27.0,<2",
@@ -31,6 +32,7 @@ dependencies = [
     "pyarrow>=23.0.1,<24",
     "PyYAML>=6.0.3,<7",
     "sentence-transformers>=5.4.0,<6",
+    "transformers>=4.48.3,<=5.5.3",
     "tree-sitter>=0.25.2,<0.26",
     "tree-sitter-java>=0.23.5,<0.24",
     "unidiff>=0.7.3,<1",

java_codebase_rag-0.2.2/tests/test_agent_skills_static.py

@@ -0,0 +1,250 @@
+"""Static validation for skills/ directory SKILL.md files.
+
+Imports allowlists from production code (mcp_v2, java_ontology) — not
+hand-maintained lists. Validates:
+  - frontmatter (name + description present)
+  - MCP tool names referenced in skill body
+  - find kind values
+  - direction values
+  - edge_types values
+  - worked example section present
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import get_args
+
+from java_ontology import NodeKind
+from mcp_v2 import ComposedEdgeType, EdgeType
+
+# ---------------------------------------------------------------------------
+# Allowlists sourced from production code
+# ---------------------------------------------------------------------------
+
+_VALID_TOOLS: frozenset[str] = frozenset(["search", "find", "describe", "neighbors", "resolve"])
+
+_VALID_KINDS: frozenset[str] = frozenset(k.lower() for k in get_args(NodeKind))
+
+_VALID_DIRECTIONS: frozenset[str] = frozenset(["in", "out"])
+
+_ALL_EDGE_TYPES: frozenset[str] = frozenset(get_args(EdgeType)) | frozenset(get_args(ComposedEdgeType))
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+SKILLS_DIR = Path(__file__).resolve().parent.parent / "skills"
+SKILL_NAME = "explore-codebase"
+EXPECTED_SKILL_DIRS = {"explore-codebase", "navigate-codebase"}
+SKILL_PATH = SKILLS_DIR / SKILL_NAME / "SKILL.md"
+
+
+def _parse_frontmatter(text: str) -> dict[str, str]:
+    """Parse simple YAML frontmatter (key: value pairs only)."""
+    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
+    if not m:
+        return {}
+    result: dict[str, str] = {}
+    for line in m.group(1).splitlines():
+        if ":" in line:
+            key, _, value = line.partition(":")
+            result[key.strip()] = value.strip()
+    return result
+
+
+def _read_skill() -> tuple[dict[str, str], str]:
+    """Read the explore-codebase SKILL.md and return (frontmatter, body)."""
+    text = SKILL_PATH.read_text(encoding="utf-8")
+    fm = _parse_frontmatter(text)
+    body = re.sub(r"^---\n.*?\n---\n*", "", text, count=1, flags=re.DOTALL)
+    return fm, body
+
+
+def _extract_tool_refs(body: str) -> set[str]:
+    """Extract tool names referenced in MCP call patterns."""
+    refs: set[str] = set()
+    for m in re.finditer(r"`(search|find|describe|neighbors|resolve)\b", body):
+        refs.add(m.group(1))
+    for m in re.finditer(r"\b(search|find|describe|neighbors|resolve)\s*[\(\{]", body):
+        refs.add(m.group(1))
+    return refs
+
+
+def _extract_kind_refs(body: str) -> set[str]:
+    """Extract find kind values from skill body."""
+    refs: set[str] = set()
+    for m in re.finditer(r'kind\s*=\s*["\']?(\w+)["\']?', body):
+        val = m.group(1).lower()
+        if val in _VALID_KINDS:
+            refs.add(val)
+    return refs
+
+
+def _extract_direction_refs(body: str) -> set[str]:
+    """Extract direction values from skill body."""
+    refs: set[str] = set()
+    for m in re.finditer(r'direction\s*:\s*["\']?(in|out)["\']?', body):
+        refs.add(m.group(1))
+    return refs
+
+
+def _extract_edge_type_refs(body: str) -> set[str]:
+    """Extract edge_types values referenced in skill body."""
+    refs: set[str] = set()
+    for m in re.finditer(r'edge_types\s*:\s*\[([^\]]+)\]', body):
+        inner = m.group(1)
+        for val in re.findall(r'"(\w[\w.]*)"', inner):
+            if val in _ALL_EDGE_TYPES:
+                refs.add(val)
+    for m in re.finditer(r'\["(\w[\w.]*)"', body):
+        val = m.group(1)
+        if val in _ALL_EDGE_TYPES:
+            refs.add(val)
+    return refs
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+
+class TestSkillFrontmatter:
+    """SKILL.md must have valid frontmatter."""
+
+    def test_skill_file_exists(self):
+        assert SKILL_PATH.is_file(), f"Missing {SKILL_PATH}"
+
+    def test_frontmatter_has_name_and_description(self):
+        fm, _ = _read_skill()
+        assert "name" in fm, "SKILL.md missing frontmatter 'name'"
+        assert fm["name"] == SKILL_NAME, f"name={fm['name']!r}, expected {SKILL_NAME!r}"
+        assert "description" in fm, "SKILL.md missing frontmatter 'description'"
+        assert len(fm["description"]) >= 20, (
+            f"description too short ({len(fm['description'])} chars)"
+        )
+
+
+class TestMCPToolReferences:
+    """Tool names in skill body must be valid MCP navigation tools."""
+
+    def test_tool_refs_are_valid(self):
+        _, body = _read_skill()
+        refs = _extract_tool_refs(body)
+        invalid = refs - _VALID_TOOLS
+        assert not invalid, f"SKILL.md references invalid tools: {invalid}"
+
+    def test_skill_references_all_five_tools(self):
+        _, body = _read_skill()
+        refs = _extract_tool_refs(body)
+        missing = _VALID_TOOLS - refs
+        assert not missing, f"SKILL.md does not reference all 5 tools, missing: {missing}"
+
+
+class TestKindAndEdgeReferences:
+    """Kind, direction, and edge_type values must match production allowlists."""
+
+    def test_kind_refs_are_valid(self):
+        _, body = _read_skill()
+        refs = _extract_kind_refs(body)
+        invalid = refs - _VALID_KINDS
+        assert not invalid, f"SKILL.md references invalid find kinds: {invalid}"
+
+    def test_direction_refs_are_valid(self):
+        _, body = _read_skill()
+        refs = _extract_direction_refs(body)
+        invalid = refs - _VALID_DIRECTIONS
+        assert not invalid, f"SKILL.md references invalid directions: {invalid}"
+
+    def test_edge_type_refs_are_valid(self):
+        _, body = _read_skill()
+        refs = _extract_edge_type_refs(body)
+        invalid = refs - _ALL_EDGE_TYPES
+        assert not invalid, f"SKILL.md references invalid edge_types: {invalid}"
+
+
+class TestBodyStructure:
+    """Skill body must contain key sections."""
+
+    def test_has_worked_example(self):
+        _, body = _read_skill()
+        assert "## Worked example" in body, "SKILL.md missing '## Worked example'"
+
+    def test_has_decision_tree(self):
+        _, body = _read_skill()
+        assert "## Decision tree" in body, "SKILL.md missing '## Decision tree'"
+
+    def test_has_recovery_playbook(self):
+        _, body = _read_skill()
+        assert "## Recovery playbook" in body, "SKILL.md missing '## Recovery playbook'"
+
+    def test_has_edge_taxonomy(self):
+        _, body = _read_skill()
+        assert "## Edge taxonomy" in body, "SKILL.md missing '## Edge taxonomy'"
+
+    def test_has_navigation_patterns(self):
+        _, body = _read_skill()
+        assert "## Common navigation patterns" in body, "SKILL.md missing '## Common navigation patterns'"
+
+    def test_has_reasoning_preamble(self):
+        _, body = _read_skill()
+        assert "## Forced reasoning preamble" in body, "SKILL.md missing '## Forced reasoning preamble'"
+
+
+class TestDirectoryIntegrity:
+    """skills/ must have expected structure."""
+
+    def test_skill_dir_exists(self):
+        assert (SKILLS_DIR / SKILL_NAME).is_dir(), f"skills/{SKILL_NAME}/ missing"
+
+    def test_no_tier_dirs(self):
+        """Old tier-1/ and tier-2/ directories must not exist."""
+        for tier in ("tier-1", "tier-2"):
+            assert not (SKILLS_DIR / tier).is_dir(), f"Old skills/{tier}/ still exists — remove it"
+
+    def test_readme_exists(self):
+        assert (SKILLS_DIR / "README.md").is_file(), "skills/README.md missing"
+
+    def test_no_other_skill_dirs(self):
+        """Only documented consumer skill directories should exist."""
+        skill_dirs = {
+            p.name for p in SKILLS_DIR.iterdir()
+            if p.is_dir() and (p / "SKILL.md").exists()
+        }
+        assert skill_dirs == EXPECTED_SKILL_DIRS, (
+            f"Expected only documented skills {EXPECTED_SKILL_DIRS}, found: {skill_dirs}"
+        )
+
+
+class TestAgentGuideConsistency:
+    """AGENT-GUIDE.md copy-paste block must be self-contained."""
+
+    def test_guide_has_navigation_patterns_table(self):
+        """The copy-paste block must include a navigation patterns section."""
+        guide = Path(__file__).resolve().parent.parent / "docs" / "AGENT-GUIDE.md"
+        text = guide.read_text(encoding="utf-8")
+        begin = text.find("<!-- BEGIN java-codebase-rag MCP guide -->")
+        end = text.find("<!-- END java-codebase-rag MCP guide -->")
+        assert begin != -1 and end != -1, "AGENT-GUIDE.md missing BEGIN/END markers"
+        block = text[begin:end]
+        assert "### Common navigation patterns" in block, (
+            "AGENT-GUIDE.md copy-paste block missing '### Common navigation patterns'"
+        )
+        for pattern in ["CALLS", "EXPOSES", "IMPLEMENTS", "INJECTS"]:
+            assert pattern in block, f"AGENT-GUIDE.md copy-paste block missing {pattern} pattern"
+
+    def test_guide_copy_block_does_not_reference_skills_dir(self):
+        """The copy-paste block must not reference skills/ — it won't exist
+        in the consumer's project."""
+        guide = Path(__file__).resolve().parent.parent / "docs" / "AGENT-GUIDE.md"
+        text = guide.read_text(encoding="utf-8")
+        begin = text.find("<!-- BEGIN java-codebase-rag MCP guide -->")
+        end = text.find("<!-- END java-codebase-rag MCP guide -->")
+        assert begin != -1 and end != -1, "AGENT-GUIDE.md missing BEGIN/END markers"
+        block = text[begin:end]
+        assert "skills/" not in block, (
+            "AGENT-GUIDE.md copy-paste block references skills/ — "
+            "this path won't resolve in a consumer project. "
+            "Keep skills/ references outside the copy-paste block."
+        )

java_codebase_rag-0.2.2/tests/test_packaging_metadata.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+
+def test_published_package_installs_cocoindex_for_lifecycle_commands() -> None:
+    data = tomllib.loads((Path(__file__).resolve().parents[1] / "pyproject.toml").read_text())
+    deps = data["project"]["dependencies"]
+
+    cocoindex_deps = [dep for dep in deps if dep.startswith("cocoindex")]
+
+    assert cocoindex_deps
+    assert any("[lancedb]" in dep for dep in cocoindex_deps)

java_codebase_rag-0.2.0/tests/test_agent_skills_static.py

@@ -1,318 +0,0 @@
-"""Static validation for skills/ directory SKILL.md files.
-
-Imports allowlists from production code (mcp_v2, java_ontology) — not
-hand-maintained lists. Validates:
-  - frontmatter (name + description present)
-  - MCP tool names referenced in skill bodies
-  - find kind values
-  - direction values
-  - edge_types values
-  - Tier 2 body structure (stop conditions, recursion limit)
-
-Known gap (intentional — see AGENT-SKILLS-AND-COMMANDS-PROPOSE §11):
-  - edge_filter parameters (callee_declaring_role, min_confidence,
-    exclude_callee_declaring_roles, dedup_calls, include_unresolved)
-    referenced in /mini-map are NOT validated against mcp_v2 parameter
-    definitions. The static validator does not parse edge_filter dicts.
-    On re-index, manually verify /mini-map against the MCP surface.
-"""
-
-from __future__ import annotations
-
-import re
-from pathlib import Path
-from typing import get_args
-
-import pytest
-
-from java_ontology import NodeKind
-from mcp_v2 import ComposedEdgeType, EdgeType
-
-# ---------------------------------------------------------------------------
-# Allowlists sourced from production code
-# ---------------------------------------------------------------------------
-
-_VALID_TOOLS: frozenset[str] = frozenset(["search", "find", "describe", "neighbors", "resolve"])
-
-_VALID_KINDS: frozenset[str] = frozenset(k.lower() for k in get_args(NodeKind))
-
-_VALID_DIRECTIONS: frozenset[str] = frozenset(["in", "out"])
-
-_ALL_EDGE_TYPES: frozenset[str] = frozenset(get_args(EdgeType)) | frozenset(get_args(ComposedEdgeType))
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-SKILLS_DIR = Path(__file__).resolve().parent.parent / "skills"
-
-TIER1_NAMES = [
-    "nl", "controllers", "routes", "clients", "producers",
-    "callers", "callees", "handlers", "who-hits-route",
-    "implements", "injects",
-]
-
-TIER2_NAMES = [
-    "explain-feature", "impact-of", "trace-request-flow", "mini-map",
-]
-
-ALL_SKILL_NAMES = TIER1_NAMES + TIER2_NAMES
-
-
-def _parse_frontmatter(text: str) -> dict[str, str]:
-    """Parse simple YAML frontmatter (key: value pairs only)."""
-    m = re.match(r"^---\n(.*?)\n---", text, re.DOTALL)
-    if not m:
-        return {}
-    result: dict[str, str] = {}
-    for line in m.group(1).splitlines():
-        if ":" in line:
-            key, _, value = line.partition(":")
-            result[key.strip()] = value.strip()
-    return result
-
-
-def _extract_tool_refs(body: str) -> set[str]:
-    """Extract tool names referenced in MCP call patterns."""
-    # Match patterns like `search(...)`, `find(kind=...)`, `describe(id=...)`,
-    # `neighbors({ids:`, `resolve(identifier=`, also backtick-wrapped names.
-    refs: set[str] = set()
-    for m in re.finditer(r"`(search|find|describe|neighbors|resolve)\b", body):
-        refs.add(m.group(1))
-    # Also catch patterns like search(query=...)  find(kind=...) without backticks
-    for m in re.finditer(r"\b(search|find|describe|neighbors|resolve)\s*[\(\{]", body):
-        refs.add(m.group(1))
-    return refs
-
-
-def _extract_kind_refs(body: str) -> set[str]:
-    """Extract find kind values from skill body."""
-    refs: set[str] = set()
-    for m in re.finditer(r'kind\s*=\s*["\']?(\w+)["\']?', body):
-        val = m.group(1).lower()
-        if val in _VALID_KINDS:
-            refs.add(val)
-    return refs
-
-
-def _extract_direction_refs(body: str) -> set[str]:
-    """Extract direction values from skill body."""
-    refs: set[str] = set()
-    for m in re.finditer(r'direction\s*:\s*["\']?(in|out)["\']?', body):
-        refs.add(m.group(1))
-    return refs
-
-
-def _extract_edge_type_refs(body: str) -> set[str]:
-    """Extract edge_types values referenced in skill body."""
-    refs: set[str] = set()
-    # Match edge_types lists: ["CALLS"] or ["HTTP_CALLS","ASYNC_CALLS","EXPOSES"]
-    for m in re.finditer(r'edge_types\s*:\s*\[([^\]]+)\]', body):
-        inner = m.group(1)
-        for val in re.findall(r'"(\w[\w.]*)"', inner):
-            if val in _ALL_EDGE_TYPES:
-                refs.add(val)
-    # Also match quoted edge names in backticked patterns
-    for m in re.finditer(r'\["(\w[\w.]*)"', body):
-        val = m.group(1)
-        if val in _ALL_EDGE_TYPES:
-            refs.add(val)
-    return refs
-
-
-def _read_skill(name: str) -> tuple[dict[str, str], str]:
-    """Read a skill's SKILL.md and return (frontmatter, body)."""
-    path = SKILLS_DIR / name / "SKILL.md"
-    text = path.read_text(encoding="utf-8")
-    fm = _parse_frontmatter(text)
-    # Body is everything after the closing ---
-    body = re.sub(r"^---\n.*?\n---\n*", "", text, count=1, flags=re.DOTALL)
-    return fm, body
-
-
-# ---------------------------------------------------------------------------
-# Parametrized test ids
-# ---------------------------------------------------------------------------
-
-@pytest.fixture(params=ALL_SKILL_NAMES, ids=lambda n: f"skill:{n}")
-def skill_name(request):
-    return request.param
-
-
-# ---------------------------------------------------------------------------
-# Tests
-# ---------------------------------------------------------------------------
-
-
-class TestSkillFrontmatter:
-    """Every SKILL.md must have valid frontmatter."""
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_frontmatter_has_name_and_description(self, name: str):
-        fm, _ = _read_skill(name)
-        assert "name" in fm, f"skills/{name}/SKILL.md missing frontmatter 'name'"
-        assert fm["name"] == name, f"skills/{name}/SKILL.md: name={fm['name']!r}, expected {name!r}"
-        assert "description" in fm, f"skills/{name}/SKILL.md missing frontmatter 'description'"
-        assert len(fm["description"]) >= 20, (
-            f"skills/{name}/SKILL.md description too short ({len(fm['description'])} chars)"
-        )
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_skill_file_exists(self, name: str):
-        path = SKILLS_DIR / name / "SKILL.md"
-        assert path.is_file(), f"Missing skills/{name}/SKILL.md"
-
-
-class TestMCPToolReferences:
-    """Tool names in skill bodies must be valid MCP navigation tools."""
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_tool_refs_are_valid(self, name: str):
-        _, body = _read_skill(name)
-        refs = _extract_tool_refs(body)
-        invalid = refs - _VALID_TOOLS
-        assert not invalid, f"skills/{name}/SKILL.md references invalid tools: {invalid}"
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_skill_references_at_least_one_tool(self, name: str):
-        _, body = _read_skill(name)
-        refs = _extract_tool_refs(body)
-        assert refs, f"skills/{name}/SKILL.md references no MCP tools"
-
-
-class TestKindAndEdgeReferences:
-    """Kind, direction, and edge_type values must match production allowlists."""
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_kind_refs_are_valid(self, name: str):
-        _, body = _read_skill(name)
-        refs = _extract_kind_refs(body)
-        invalid = refs - _VALID_KINDS
-        assert not invalid, f"skills/{name}/SKILL.md references invalid find kinds: {invalid}"
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_direction_refs_are_valid(self, name: str):
-        _, body = _read_skill(name)
-        refs = _extract_direction_refs(body)
-        invalid = refs - _VALID_DIRECTIONS
-        assert not invalid, f"skills/{name}/SKILL.md references invalid directions: {invalid}"
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_edge_type_refs_are_valid(self, name: str):
-        _, body = _read_skill(name)
-        refs = _extract_edge_type_refs(body)
-        invalid = refs - _ALL_EDGE_TYPES
-        assert not invalid, f"skills/{name}/SKILL.md references invalid edge_types: {invalid}"
-
-
-class TestTier2BodyStructure:
-    """Tier 2 skills must have stop conditions and recursion limits."""
-
-    @pytest.mark.parametrize("name", TIER2_NAMES)
-    def test_has_stop_conditions(self, name: str):
-        _, body = _read_skill(name)
-        assert "## Stop conditions" in body, f"skills/{name}/SKILL.md missing '## Stop conditions'"
-
-    @pytest.mark.parametrize("name", TIER2_NAMES)
-    def test_has_recursion_limit(self, name: str):
-        _, body = _read_skill(name)
-        assert "## Recursion limit" in body, f"skills/{name}/SKILL.md missing '## Recursion limit'"
-
-    def test_mini_map_has_classification_rules(self):
-        _, body = _read_skill("mini-map")
-        assert "### Step 4 — Skill heuristics" in body or "Classification" in body, (
-            "skills/mini-map/SKILL.md missing classification rules"
-        )
-
-    def test_mini_map_has_output_shape(self):
-        _, body = _read_skill("mini-map")
-        assert "PERSISTS" in body and "DELEGATES" in body, (
-            "skills/mini-map/SKILL.md missing output shape (PERSISTS/DELEGATES labels)"
-        )
-
-
-class TestWorkedExamples:
-    """Every skill must have a worked example section."""
-
-    @pytest.mark.parametrize("name", ALL_SKILL_NAMES)
-    def test_has_worked_example(self, name: str):
-        _, body = _read_skill(name)
-        assert "## Worked example" in body, f"skills/{name}/SKILL.md missing '## Worked example'"
-
-
-class TestDirectoryIntegrity:
-    """skills/ directory must contain exactly the expected skills."""
-
-    def test_no_extra_skill_dirs(self):
-        actual = {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
-        expected = set(ALL_SKILL_NAMES)
-        extra = actual - expected
-        assert not extra, f"Unexpected skill directories: {extra}"
-
-    def test_no_missing_skill_dirs(self):
-        actual = {p.name for p in SKILLS_DIR.iterdir() if p.is_dir() and (p / "SKILL.md").exists()}
-        expected = set(ALL_SKILL_NAMES)
-        missing = expected - actual
-        assert not missing, f"Missing skill directories: {missing}"
-
-    def test_readme_exists(self):
-        assert (SKILLS_DIR / "README.md").is_file(), "skills/README.md missing"
-
-
-class TestAgentGuideConsistency:
-    """AGENT-GUIDE.md copy-paste block must be self-contained."""
-
-    def test_guide_has_navigation_patterns_table(self):
-        """The copy-paste block must include a navigation patterns section
-        (it's standalone — no external file references work in a consumer project)."""
-        guide = Path(__file__).resolve().parent.parent / "docs" / "AGENT-GUIDE.md"
-        text = guide.read_text(encoding="utf-8")
-        # Extract the copy-paste block (marker on its own line)
-        begin = text.find("<!-- BEGIN java-codebase-rag MCP guide -->")
-        end = text.find("<!-- END java-codebase-rag MCP guide -->")
-        assert begin != -1 and end != -1, "AGENT-GUIDE.md missing BEGIN/END markers"
-        block = text[begin:end]
-        assert "### Common navigation patterns" in block, (
-            "AGENT-GUIDE.md copy-paste block missing '### Common navigation patterns'"
-        )
-        # Verify key patterns are present
-        for pattern in ["CALLS", "EXPOSES", "IMPLEMENTS", "INJECTS"]:
-            assert pattern in block, f"AGENT-GUIDE.md copy-paste block missing {pattern} pattern"
-
-    def test_guide_copy_block_does_not_reference_skills_dir(self):
-        """The copy-paste block must not reference skills/ — it won't exist
-        in the consumer's project."""
-        guide = Path(__file__).resolve().parent.parent / "docs" / "AGENT-GUIDE.md"
-        text = guide.read_text(encoding="utf-8")
-        begin = text.find("<!-- BEGIN java-codebase-rag MCP guide -->")
-        end = text.find("<!-- END java-codebase-rag MCP guide -->")
-        assert begin != -1 and end != -1, "AGENT-GUIDE.md missing BEGIN/END markers"
-        block = text[begin:end]
-        assert "skills/" not in block, (
-            "AGENT-GUIDE.md copy-paste block references skills/ — "
-            "this path won't resolve in a consumer project. "
-            "Keep skills/ references outside the copy-paste block."
-        )
-
-    def test_guide_copy_block_has_no_slash_command_aliases(self):
-        """The copy-paste block must not contain slash-command alias bullets
-        like `/nl <text>` → ... — these imply commands that don't exist
-        and will mislead the agent. Incidental mentions (e.g. cross-references
-        in prose) are fine."""
-        guide = Path(__file__).resolve().parent.parent / "docs" / "AGENT-GUIDE.md"
-        text = guide.read_text(encoding="utf-8")
-        begin = text.find("<!-- BEGIN java-codebase-rag MCP guide -->")
-        end = text.find("<!-- END java-codebase-rag MCP guide -->")
-        block = text[begin:end]
-        # Match alias definition lines: - `/skillname ...` → tool(...)
-        skill_names_pattern = "|".join(re.escape(n) for n in ALL_SKILL_NAMES)
-        alias_pattern = re.compile(
-            rf"^- `/(?:{skill_names_pattern})\s",
-            re.MULTILINE,
-        )
-        matches = alias_pattern.findall(block)
-        assert not matches, (
-            f"AGENT-GUIDE.md copy-paste block contains slash-command alias bullets: "
-            f"{alias_pattern.findall(block)}. "
-            "These are not real commands and will mislead the agent."
-        )