Add LightRAG-parity: knowledge graph, semantic tags, graph search

.claude/skills/add-javaducker/add-javaducker.md

@@ -0,0 +1,114 @@
+---
+name: add-javaducker
+description: Configure JavaDucker as an optional companion tool for semantic code search and indexing
+user-invocable: true
+---
+
+# Add JavaDucker
+
+You are setting up JavaDucker as a companion tool for this project. JavaDucker provides semantic code indexing, search, dependency analysis, and project mapping via MCP tools.
+
+## What you need
+
+The user must provide the **JavaDucker root folder** — the directory containing `JavaDuckerMcpServer.java` and `run-mcp.sh`.
+
+If the user doesn't provide a path, look for it in sibling directories:
+- `../code-helper`
+- `../javaducker`
+
+## Setup Process
+
+1. **Get the path** — ask the user or auto-detect from sibling directories
+
+2. **Validate** — confirm these files exist at the root:
+   - `JavaDuckerMcpServer.java`
+   - `run-mcp.sh`
+   - `run-server.sh`
+   If any are missing, stop and report the error.
+
+3. **Create local data directory** — create `.claude/.javaducker/` in the project root:
+   ```bash
+   mkdir -p .claude/.javaducker/intake
+   ```
+   This is where the DuckDB database and intake files live — per-project, gitignored.
+
+4. **Find a free port** — scan ports 8080-8180 to find one that's not in use:
+   ```bash
+   for port in $(seq 8080 8180); do
+     if ! (echo >/dev/tcp/localhost/$port) 2>/dev/null; then
+       echo "Using port $port"
+       break
+     fi
+   done
+   ```
+
+5. **Write config** — create `.claude/.state/javaducker.conf`:
+   ```
+   JAVADUCKER_ROOT=/absolute/path/to/javaducker
+   JAVADUCKER_HTTP_PORT=<free port found in step 4>
+   JAVADUCKER_DB=/absolute/path/to/project/.claude/.javaducker/javaducker.duckdb
+   JAVADUCKER_INTAKE=/absolute/path/to/project/.claude/.javaducker/intake
+   ```
+   All paths must be absolute.
+
+6. **Register MCP server** — create or merge `.mcp.json` in the project root:
+   ```json
+   {
+     "mcpServers": {
+       "javaducker": {
+         "command": "jbang",
+         "args": ["JAVADUCKER_ROOT/JavaDuckerMcpServer.java"],
+         "env": {
+           "PROJECT_ROOT": "<project root absolute path>",
+           "HTTP_PORT": "<port from step 4>"
+         }
+       }
+     }
+   }
+   ```
+   Replace placeholders with actual absolute paths and port.
+
+   **If `.mcp.json` already exists**, read it first and merge the `javaducker` key into the existing `mcpServers` object. Do not overwrite other MCP servers.
+
+7. **Start the server** — launch with project-local data paths:
+   ```bash
+   DB=<JAVADUCKER_DB> HTTP_PORT=<port> INTAKE_DIR=<JAVADUCKER_INTAKE> \
+     nohup bash <JAVADUCKER_ROOT>/run-server.sh >/dev/null 2>&1 &
+   ```
+   Wait up to 10 seconds for it to become healthy (poll `/api/health`). The server auto-starts on future sessions via the memory-sync hook using `javaducker_start()`.
+
+8. **Index the project** — once the server is healthy, use `javaducker_index_directory` with the project root. Or via CLI:
+   ```bash
+   bash <JAVADUCKER_ROOT>/run-client.sh --port <port> upload-dir --root <PROJECT_DIR> --ext .java,.xml,.md,.yml,.yaml,.json,.properties,.gradle,.kt,.py,.go,.rs,.ts,.js
+   ```
+
+9. **Index past sessions** (optional) — ask the user if they want to index past Claude Code sessions. If yes, use `javaducker_index_sessions`.
+
+10. **Confirm setup** — print a short confirmation:
+    ```
+    JavaDucker ready. Look for "JD" in the statusline.
+      Root:     /path/to/javaducker
+      Port:     <port>
+      Database: .claude/.javaducker/javaducker.duckdb
+      Intake:   .claude/.javaducker/intake/
+      Index:    started for current project
+    ```
+
+## How it works for the user
+
+After setup, JavaDucker is invisible:
+- **Statusline** shows `JD` when active, `JD(off)` if the server is down
+- **Server auto-starts** on each session — finds a free port if the saved one is taken
+- **Data stays local** — each project has its own database in `.claude/.javaducker/`
+- **Edited files auto-index** via the post-edit hook
+- **All drom-flow skills** automatically use JavaDucker for deeper search when available
+- **No CLI commands needed** — everything happens through MCP tools and hooks
+
+To remove: use `/remove-javaducker`
+
+## Important notes
+
+- First MCP connection may take 10-20 seconds (jbang compiles the Java file on first run)
+- `.mcp.json` and `.claude/.javaducker/` are gitignored (machine-specific)
+- The config is machine-specific — each developer runs `/add-javaducker` once
+- Multiple projects can run simultaneously — each gets its own port and database

.claude/skills/architect/architect.md

@@ -11,7 +11,8 @@ You are a software architect. Your job is to design systems and make technology
 ## Responsibilities
 
 1. **Analyze requirements** — understand what the system needs to do, now and in the near future
-2. **Evaluate trade-offs** — compare approaches by complexity, performance, maintainability
+2. **If JavaDucker is available** — use `javaducker_search` to find existing implementations of similar patterns. Use `javaducker_map` for project structure orientation. Use `javaducker_dependencies` to understand the current dependency graph. Use `javaducker_concepts` for the concept map across the corpus. Use `javaducker_find_by_type` with `ADR` or `DESIGN_DOC` to find existing architecture decisions. Use `javaducker_recent_decisions` to check for decisions made in past sessions. Use `javaducker_session_context` for historical discussion on the topic.
+3. **Evaluate trade-offs** — compare approaches by complexity, performance, maintainability
 3. **Design interfaces** — define how components talk to each other
 4. **Document decisions** — write ADRs in `context/DECISIONS.md`
 5. **Consider constraints** — team size, timeline, existing tech stack
@@ -44,6 +45,15 @@ You are a software architect. Your job is to design systems and make technology
 **Consequences:** [What follows from this]
 ```
 
+## Knowledge curation (when JavaDucker is available)
+
+After completing your design work, you are responsible for curating the knowledge you produced:
+
+1. **Record the decision** — `javaducker_extract_decisions` with the session ID and each decision you made (what, why, alternatives rejected). Tag with the domain area. These become searchable via `javaducker_recent_decisions` in future sessions.
+2. **Check for invalidated decisions** — `javaducker_find_points` with `DECISION` type. Read each prior decision that overlaps with your new design. If your new decision supersedes an old one, use `javaducker_set_freshness` to mark the old artifact as `superseded` (with `superseded_by` pointing to the new one). Then `javaducker_synthesize` the old artifact — write a summary that says what it decided, why it's no longer valid, and what replaced it.
+3. **Link concepts** — `javaducker_link_concepts` to connect your new design's concepts to related artifacts. This builds the concept graph that `javaducker_concepts` and `javaducker_concept_timeline` expose.
+4. **Classify your output** — if the ADR or design doc gets indexed, `javaducker_classify` it as `ADR` or `DESIGN_DOC` so future architects can find it with `javaducker_find_by_type`.
+
 ## Principles
 
 - Design for what you know, not what you imagine

.claude/skills/debugger/debugger.md

@@ -21,7 +21,8 @@ You are a debugger. Your job is to systematically find and fix the root cause of
 
 1. Gather symptoms: error messages, stack traces, logs, steps to reproduce
 2. Read the code path involved — trace from entry point to failure
-3. Form 2-3 hypotheses ranked by likelihood
+3. **If JavaDucker is available** — use `javaducker_search` for error messages and exception names. Use `javaducker_explain` on suspect files for dependencies and co-change history. Use `javaducker_dependents` to find callers that might be passing bad input. Use `javaducker_related` to find co-changed files that may also be involved. Use `javaducker_blame` on the suspect region to see who changed it and when. Use `javaducker_search_sessions` to check if this bug was discussed in prior sessions.
+4. Form 2-3 hypotheses ranked by likelihood
 4. Test each hypothesis with targeted investigation (grep, read, run)
 5. Once root cause is found, implement the minimal fix
 6. Add a test that fails without the fix and passes with it
@@ -45,6 +46,15 @@ You are a debugger. Your job is to systematically find and fix the root cause of
 - [Test that was added or run]
 ```
 
+## Knowledge curation (when JavaDucker is available)
+
+After resolving a bug, record what you learned:
+
+1. **Record the root cause as a point** — `javaducker_extract_points` on the affected file's artifact with type `INSIGHT` describing the root cause and why it was non-obvious. Future debuggers searching for similar symptoms will find this.
+2. **Record the decision** — `javaducker_extract_decisions` with the fix decision (what was changed, why this approach, what alternatives were considered).
+3. **Tag the file** — `javaducker_tag` the affected artifact with bug-related tags (e.g., the error type, the component area) so `javaducker_find_by_tag` can surface it later.
+4. **Check for stale workarounds** — if your fix resolves a root cause that had prior workarounds documented, `javaducker_set_freshness` → `superseded` on those workaround artifacts. Synthesize them with a note that the root cause is now fixed.
+
 ## Principles
 
 - Never guess — verify each assumption by reading code or running tests

.claude/skills/implementer/implementer.md

@@ -20,10 +20,19 @@ You are a code implementer. Your job is to write clean, correct, production-read
 
 1. Read the relevant files to understand existing patterns
 2. Check `context/CONVENTIONS.md` for naming, imports, error handling patterns
-3. Implement the change with minimal diff
+3. **If JavaDucker is available** — use `javaducker_search` (semantic mode) to find related patterns, similar implementations, and conventions that Grep alone might miss. Use `javaducker_explain` on key files for full context. For Java/Reladomo projects, use `javaducker_reladomo_relationships` to understand object models, `javaducker_reladomo_graph` to visualize relationship chains, `javaducker_reladomo_finders` for query patterns, and `javaducker_reladomo_deepfetch` for eager loading profiles. Use `javaducker_related` to find co-changed files that should be updated together.
+4. Implement the change with minimal diff
 4. Run tests to verify nothing broke
 5. Self-review: is this the simplest correct solution?
 
+## Knowledge curation (when JavaDucker is available)
+
+After implementing a change, update the knowledge base:
+
+1. **Tag new patterns** — if you introduced a new pattern or convention, `javaducker_tag` the file with descriptive tags so future implementers can find it via `javaducker_find_by_tag`.
+2. **Record non-obvious decisions** — if you made a judgment call (chose approach A over B), `javaducker_extract_decisions` to record it with context. Future sessions will surface it via `javaducker_recent_decisions`.
+3. **Mark superseded code** — if your change replaces or deprecates an older implementation, `javaducker_set_freshness` → `superseded` on the old artifact, then `javaducker_synthesize` with a summary of what it did and why it was replaced.
+
 ## Principles
 
 - Prefer editing existing files over creating new ones

.claude/skills/orchestrator/orchestrator.md

@@ -20,7 +20,8 @@ You are a pipeline orchestrator. Your job is to run closed-loop workflows that c
 ## Process
 
 1. Read the workflow file (e.g., `workflows/closed-loop.md`)
-2. Run the check command or orchestration script
+2. **If JavaDucker is available** — use `javaducker_index_health` to check overall index freshness. Use `javaducker_stale` with `git_diff_ref: "HEAD~1"` to find stale files. Re-index stale files before starting. After each iteration, use `javaducker_extract_points` to record key findings (RISK, ACTION, INSIGHT) from the iteration. Use `javaducker_concept_health` to monitor concept trends across iterations. Use `javaducker_synthesize` on completed/obsolete artifacts to keep the index compact.
+3. Run the check command or orchestration script
 3. Parse the JSON report
 4. Group issues into independent categories
 5. For each category, spawn an Agent with `run_in_background: true`:
@@ -74,6 +75,16 @@ After each iteration, log:
 - Next: [continue/revert/done]
 ```
 
+## Post-loop: Knowledge curation (when JavaDucker is available)
+
+After the loop exits, you are responsible for curating what was learned:
+
+1. **Record what worked and what didn't** — `javaducker_extract_decisions` with each key decision: what fix strategies worked, what regressed and why, the final approach chosen. Tag with the domain area. This is critical — future orchestrators will find these via `javaducker_recent_decisions` and avoid repeating failed approaches.
+2. **Extract insights** — for each file that was fixed, `javaducker_extract_points` with type `INSIGHT` recording what the root issue was. Type `RISK` for any fragile areas you noticed. Type `ACTION` for any follow-up work needed.
+3. **Enrich new artifacts** — `javaducker_enrich_queue` for files edited during the loop. Read each, then `javaducker_classify`, `javaducker_extract_points`, `javaducker_tag`, `javaducker_mark_enriched`. Don't classify blindly — read the content first.
+4. **Supersede obsolete intermediate states** — iterations that were reverted produced artifacts that are now noise. `javaducker_set_freshness` → `superseded` on those. `javaducker_synthesize` with a note: "Reverted in iteration N because [reason]. Replaced by [final approach]."
+5. **Check for invalidated decisions** — `javaducker_find_points` with `DECISION` type. If the loop's outcome contradicts a prior recorded decision, supersede it and record the new decision.
+
 ## Principles
 
 - Always parallel — never fix issues sequentially when they're independent

.claude/skills/planner/planner.md

@@ -11,7 +11,8 @@ You are a task planner. Your job is to break down the user's request into a chap
 ## Responsibilities
 
 1. **Decompose** the task into chapters — each chapter is a logical phase of work
-2. **Break chapters into steps** — discrete, independently completable items within each chapter
+2. **If JavaDucker is available** — use `javaducker_search` to identify all files that will be affected by the task. Use `javaducker_dependents` on key files to discover downstream impact. Use `javaducker_session_context` to find prior conversations and decisions related to this area. Use `javaducker_recent_decisions` to check for relevant past decisions. This produces more accurate chapter breakdowns and catches files that Grep-based search might miss.
+3. **Break chapters into steps** — discrete, independently completable items within each chapter
 3. **Identify dependencies** — which chapters/steps must complete before others can start
 4. **Maximize parallelism** — default to parallel; only serialize when there's a true data dependency
 5. **Identify loops** — flag steps that need repeat-until-pass iteration
@@ -110,6 +111,14 @@ At session start, the memory-sync hook scans `drom-plans/` for plans with `statu
 4. **Resume from there** — do not redo completed steps
 5. **Continue tracking** progress as normal
 
+## Knowledge curation (when JavaDucker is available)
+
+When creating or completing a plan, curate the knowledge:
+
+1. **Before planning** — `javaducker_recent_decisions` and `javaducker_find_points` with `CONSTRAINT` and `RISK` types. Read the results. If any prior constraint or risk applies to your plan, incorporate it. If a prior decision has been invalidated by the current task, note it.
+2. **After plan completion** — `javaducker_extract_decisions` to record key decisions made during planning (scope choices, trade-offs, rejected approaches). Tag them so future planners find them.
+3. **Supersede old plans** — if this plan replaces or invalidates a prior plan that was indexed, `javaducker_set_freshness` → `superseded` on the old plan artifact, then `javaducker_synthesize` it with a summary of what it planned, why it's superseded, and what replaced it.
+
 ## Principles
 
 - **Parallel by default** — every step is parallel unless proven otherwise

.claude/skills/refactorer/refactorer.md

@@ -19,15 +19,24 @@ You are a refactorer. Your job is to improve code structure without changing beh
 ## Process
 
 1. Read the code to understand current structure
-2. Run existing tests to establish a passing baseline
-3. Identify specific refactoring targets with clear justification
+2. **If JavaDucker is available** — use `javaducker_dependents` on files you plan to refactor to discover all callers and importers. Use `javaducker_related` to find co-changed files. For Reladomo projects, use `javaducker_reladomo_object_files` to find all files for an object (generated, hand-written, xml, config). This ensures no reference is missed during renaming or restructuring.
+3. Run existing tests to establish a passing baseline
+4. Identify specific refactoring targets with clear justification
 4. For each change:
    a. Make one small structural change
    b. Run tests — must still pass
    c. If tests fail, revert and try a different approach
 5. Remove any dead code left behind
 6. Final test run to confirm everything passes
 
+## Knowledge curation (when JavaDucker is available)
+
+After completing a refactor, clean up the knowledge base:
+
+1. **Synthesize removed/renamed files** — if files were deleted or renamed, `javaducker_set_freshness` → `superseded` on the old artifact, then `javaducker_synthesize` with a summary noting the rename/removal and where the functionality moved to.
+2. **Update concept links** — `javaducker_link_concepts` to connect the new file structure to existing concepts. This keeps the concept graph accurate after restructuring.
+3. **Record the refactor decision** — `javaducker_extract_decisions` with why the refactor was done and the approach taken. This prevents future refactors from undoing your work.
+
 ## Principles
 
 - Behavior must not change — if tests break, the refactor is wrong

.claude/skills/remove-javaducker/remove-javaducker.md

@@ -0,0 +1,39 @@
+---
+name: remove-javaducker
+description: Remove JavaDucker companion tool configuration from this project
+user-invocable: true
+---
+
+# Remove JavaDucker
+
+You are removing the JavaDucker companion tool integration from this project.
+
+## Removal Process
+
+1. **Stop watch** — if the `javaducker_watch` MCP tool is available, call it with `action: "stop"` to stop any active file watchers. Ignore errors if the server is not running.
+
+2. **Remove config** — delete `.claude/.state/javaducker.conf` if it exists.
+
+3. **Remove project-local data** — delete `.claude/.javaducker/` if it exists. This directory contains the per-project DuckDB database and intake folder created by the auto-start lifecycle.
+
+4. **Clean MCP registration** — read `.mcp.json` in the project root:
+   - If it contains only the `javaducker` entry, delete the entire `.mcp.json` file
+   - If it contains other MCP servers too, remove only the `javaducker` key from `mcpServers` and write the file back
+
+5. **Confirm removal** — print what was removed:
+   ```
+   JavaDucker removed:
+     Deleted: .claude/.state/javaducker.conf
+     Deleted: .claude/.javaducker/ (project-local data)
+     Cleaned: .mcp.json (javaducker entry removed)
+   ```
+   Only list items that actually existed and were removed.
+
+## What is preserved
+
+- The JavaDucker installation itself (at its own root directory) is untouched
+- drom-flow hooks and skills gracefully degrade — they check for the config file and skip JavaDucker features when it's absent
+
+## To re-add later
+
+Run `/add-javaducker` with the JavaDucker root path.