GORM: Shared Mapping Registry O(M+N) Scaling

.agents/skills/repowise/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: repowise
+description: Guide for running, interpreting, and fixing code style violations in grails-core using GrailsCodeStylePlugin — covering CodeNarc, Checkstyle, PMD, SpotBugs, and Spotless
+license: Apache-2.0
+---
+
+<!-- Add your custom instructions below. Repowise will never modify anything outside the REPOWISE markers. -->
+<!-- Examples: coding style rules, test commands, workflow preferences, constraints -->
+
+## Repository Configuration
+- **Avoid repo pollution**: Do not commit local AI tooling files.
+- **Do not generate CLAUDE.md**: Use `repowise init --no-claude-md` or set `editor_files.claude_md: false` in config.
+- **Personal installation only**: Configure Repowise/MCP settings in your personal global environment (`~/.claude/` or `~/Library/Application Support/Claude/`), not in the repository root (e.g., avoid `.mcp.json` at root).
+- **Git ignore**: Always keep `.repowise/` in `.gitignore`.
+
+
+<!-- REPOWISE:START — Do not edit below this line. Auto-generated by Repowise. -->
+## IMPORTANT: Codebase Intelligence Instructions for grails-core
+
+> This repository is indexed by [Repowise](https://repowise.dev).
+> Use the MCP tools below for orientation, discovery, and enriched context
+> (documentation, ownership, history, decisions). **Always verify against
+> actual source files before making changes** — the index may be stale.
+
+Last indexed: 2026-05-16 (commit 052293a95a)
+### Entry Points
+- `grails-test-examples/gsp-spring-boot/app/src/main/java/hello/Application.java`
+- `grails-forge/grails-forge-analytics-postgres/src/main/java/org/grails/forge/analytics/postgres/Application.java`
+- `grails-forge/grails-forge-analytics-postgres/src/main/java/org/grails/forge/analytics/postgres/Main.java`
+- `grails-forge/grails-forge-cli/src/main/java/org/grails/forge/cli/Application.java`
+- `grails-forge/grails-forge-web-netty/src/main/java/org/grails/forge/netty/Application.java`
+- `grails-wrapper/src/main/java/grails/init/Start.java`
+### Tech Stack
+**Languages:** Java, Python
+**Frameworks:** Pydantic
+
+**Infra:** Gradle### Hotspots (High Churn)
+| File | Churn | 90d Commits | Owner |
+|------|-------|-------------|-------|
+| `grails-data-hibernate7/core/src/main/groovy/org/grails/orm/hibernate/query/PredicateGenerator.java` | 99.9th %ile | 47 | Walter Duque de Estrada |
+| `grails-data-hibernate7/core/src/main/groovy/org/grails/orm/hibernate/HibernateDatastore.java` | 99.9th %ile | 46 | Walter Duque de Estrada |
+| `grails-data-hibernate7/core/src/main/groovy/org/grails/orm/hibernate/query/HibernateHqlQuery.java` | 99.8th %ile | 26 | Walter Duque de Estrada |
+| `grails-data-hibernate7/core/src/main/groovy/org/grails/orm/hibernate/cfg/domainbinding/secondpass/CollectionSecondPassBinder.java` | 99.8th %ile | 62 | Walter Duque de Estrada |
+| `grails-data-hibernate7/core/src/main/groovy/grails/orm/CriteriaMethodInvoker.java` | 99.7th %ile | 27 | Walter Duque de Estrada |
+
+### Repowise MCP Tools
+
+This project has a Repowise MCP server configured. These tools provide documentation, ownership, architectural decisions, and risk signals. Use them for orientation and discovery — then read actual source to verify before editing.
+
+**Recommended workflow:**
+
+1. Start with `get_overview()` on a new task to orient yourself.
+2. Call `get_context(targets=["path/to/file.py"])` for enriched context on unfamiliar files — but always read the source before editing.
+3. Call `get_risk(targets=["path/to/file.py"])` before changing hotspot files.
+4. Don't know where something lives? Call `search_codebase(query="authentication flow")`.
+5. Need to understand why code is structured a certain way? Call `get_why(query="why JWT over sessions")` before architectural changes.
+6. After **architectural changes**, consider calling `update_decision_records(action="create", ...)` to record the rationale.
+7. Need to understand how two modules connect? Call `get_dependency_path(source="src/auth", target="src/db")`.
+8. Before cleanup tasks, call `get_dead_code()` to find confirmed unused code.
+9. For documentation or diagrams, call `get_architecture_diagram(scope="src/auth")`.
+
+**Note:** MCP tool responses reflect the last index run. If the index is stale, verify against source files.
+
+| Tool | When to use |
+|------|-------------|
+| `get_overview()` | Orient yourself on a new task |
+| `get_context(targets=[...])` | Enriched context on unfamiliar files |
+| `get_risk(targets=[...])` | Before changing hotspot files |
+| `get_why(query="...")` | Before architectural changes |
+| `update_decision_records(action=...)` | After architectural changes — record decisions |
+| `search_codebase(query="...")` | When locating code |
+| `get_dependency_path(source=..., target=...)` | When tracing module connections |
+| `get_dead_code()` | Before any cleanup or removal |
+| `get_architecture_diagram(scope=...)` | For visual structure or documentation |
+
+## Tool Overview
+
+| Tool | Purpose | Typical use |
+|------|---------|-------------|
+| `get_overview` | Architecture summary | First call on any unfamiliar codebase |
+| `get_answer` | One-call RAG Q&A | First call on any code question |
+| `get_context` | Rich context for targets | Before reading or modifying code |
+| `search_codebase` | Semantic search | Discovering code by topic |
+| `get_risk` | Modification risk | Before changing hotspot files |
+| `get_why` | Architectural decisions | Before structural changes |
+| `get_dead_code` | Unreachable code | Cleanup tasks |
+
+---
+
+## `get_overview`
+
+Architecture summary, module map, entry points, git health, and community summary.
+
+**Parameters:** None required.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `repo` | string | *(workspace only)* Target repo alias, or `"all"` |
+
+**Returns:** Architecture description, key modules with purpose and owner, entry points, tech stack, hotspot files, knowledge silos, community summary (top communities by size with labels and cohesion scores).
+
+**When to use:** First call on any unfamiliar codebase. Gives the agent a mental map before diving into specifics.
+
+**Example call:**
+
+```
+get_overview()
+```
+
+---
+
+## `get_answer`
+
+One-call RAG: retrieves over the wiki, gates synthesis on confidence, and returns a cited 2–5 sentence answer.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `question` | string | Yes | Natural language question about the codebase |
+| `repo` | string | No | *(workspace only)* Target repo alias |
+
+**Returns:** A synthesized answer with file/symbol citations and a confidence label (`high`, `medium`, `low`). High-confidence answers can be cited directly. Low-confidence answers return ranked wiki excerpts instead.
+
+**When to use:** First call on any code question. Collapses search → read → reason into one round-trip. If confidence is low, follow up with `search_codebase` to discover candidate pages.
+
+**Example call:**
+
+```
+get_answer(question="How does the authentication flow work?")
+```
+
+---
+
+## `get_context`
+
+The workhorse tool. Returns docs, symbols, ownership, freshness, and community membership for any combination of files, modules, or symbols.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `targets` | list[string] | Yes | File paths, module names, or symbol IDs. Batch multiple targets in one call. |
+| `include` | list[string] | No | Additional data to include: `"source"` (symbol body), `"callers"` (who calls this), `"callees"` (what this calls), `"metrics"` (PageRank, centrality), `"community"` (cluster membership) |
+| `compact` | boolean | No | Default `true`. Set `false` for full structure block and importer list. |
+| `repo` | string | No | *(workspace only)* Target repo alias, or `"all"` |
+
+**Returns per target:** Documentation summary, symbols defined, ownership percentages, freshness score, co-change partners, architectural decisions governing the file. With `include` options: source code, call graph, graph metrics, community membership.
+
+**When to use:** Before reading or modifying code. Pass all relevant targets in one call to minimize round-trips. In workspace mode, enriched with cross-repo co-change and contract data.
+
+**Example calls:**
+
+```
+get_context(targets=["src/auth/middleware.ts"])
+get_context(targets=["middleware", "api/routes", "payments"], include=["callers", "metrics"])
+get_context(targets=["src/auth"], compact=false, include=["community"])
+```
+
+---
+
+## `search_codebase`
+
+Semantic search over the full wiki. Natural language queries.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Natural language search query |
+| `repo` | string | No | *(workspace only)* Target repo alias, or `"all"` to search across workspace |
+
+**Returns:** Ranked wiki pages with relevance scores, snippets, and file paths.
+
+**When to use:** When `get_answer` returned low confidence and you need to discover candidate pages by topic. Also useful for broad exploration ("how do we handle retries?", "payment processing flow").
+
+In workspace mode, searches across all repos and merges results.
+
+**Example call:**
+
+```
+search_codebase(query="rate limit OR throttle OR retry")
+```
+
+---
+
+## `get_risk`
+
+Modification risk assessment for files or a set of changed files.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `targets` | list[string] | No | File paths to assess |
+| `changed_files` | list[string] | No | Files in a PR/changeset for blast radius analysis |
+| `repo` | string | No | *(workspace only)* Target repo alias |
+
+**Returns:** Per-file risk score (0–10), hotspot status, dependent count, co-change partners, blast radius, recommended reviewers, test gap analysis, security signals. In workspace mode, enriched with cross-repo co-change partners and contract dependencies.
+
+**When to use:** Before modifying files — especially hotspots. Understand what could break, who to involve in review, and whether tests cover the affected area.
+
+**Example calls:**
+
+```
+get_risk(targets=["src/auth/middleware.ts"])
+get_risk(changed_files=["src/api/routes.ts", "src/middleware/cors.ts"])
+```
+
+---
+
+## `get_why`
+
+Architectural decision intelligence. Three modes depending on parameters.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | No | Natural language query about decisions, OR a file path |
+| `repo` | string | No | *(workspace only)* Target repo alias |
+
+**Modes:**
+
+1. **NL search** — pass a question: `get_why(query="why JWT over sessions?")` → searches decision records
+2. **Path-based** — pass a file path: `get_why(query="src/auth/service.ts")` → returns decisions governing that file
+3. **Health dashboard** — no args: `get_why()` → stale decisions, conflicts, ungoverned hotspots
+
+**Returns:** Matching decision records with title, rationale, alternatives considered, affected files, staleness score. Health mode returns stale decisions, conflicts, and ungoverned hotspots.
+
+**When to use:** Before architectural changes — understand existing intent and constraints. After changes — record new decisions.
+
+**Example calls:**
+
+```
+get_why(query="rate limiting")
+get_why(query="src/payments/processor.ts")
+get_why()
+```
+
+---
+
+## `get_dead_code`
+
+Unreachable code sorted by confidence tier with cleanup impact estimates.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `min_confidence` | float | No | Minimum confidence threshold (default: 0.4) |
+| `include_internals` | boolean | No | Include private/underscore symbols (default: false) |
+| `repo` | string | No | *(workspace only)* Target repo alias |
+
+**Returns:** Dead code findings grouped by confidence tier (`safe_to_delete` ≥ 0.70, `review_first` < 0.70). Each finding includes: file path, kind (unreachable_file, unused_export, unused_internal, zombie_package), confidence score, line count, and cleanup impact estimate.
+
+**When to use:** Cleanup tasks. Conservative by design — `safe_to_delete` excludes dynamically-loaded patterns and framework-decorated functions.
+
+**Example calls:**
+
+```
+get_dead_code()
+get_dead_code(min_confidence=0.8, include_internals=true)
+```
+
+<!-- REPOWISE:END -->

.gitignore

@@ -65,6 +65,7 @@ tmp/
 !etc/bin
 etc/bin/results
 .vscode/
+.repowise/
 /scratch/
 /local.properties
 local-tasks.gradle