diff --git a/docs/JAVA-CODEBASE-RAG-CLI.md b/docs/JAVA-CODEBASE-RAG-CLI.md index f73cabc..3764d95 100644 --- a/docs/JAVA-CODEBASE-RAG-CLI.md +++ b/docs/JAVA-CODEBASE-RAG-CLI.md @@ -94,7 +94,7 @@ java-codebase-rag init --source-root /path/to/java/repo --index-dir /path/to/.ja ### `increment` -Runs cocoindex **catch-up** without a full Lance reprocess. **Does not** rebuild Kuzu. Every run prints a **multi-line stderr warning** that graph navigation may be stale until you run `reprocess` (see [`propose/CLI-SCENARIOS-PROPOSE.md`](../propose/CLI-SCENARIOS-PROPOSE.md) Appendix A for the contract). +Runs cocoindex **catch-up** without a full Lance reprocess. **Does not** rebuild Kuzu. Every run prints a **multi-line stderr warning** that graph navigation may be stale until you run `reprocess` (see [`propose/completed/CLI-SCENARIOS-PROPOSE.md`](../propose/completed/CLI-SCENARIOS-PROPOSE.md) Appendix A for the contract). ```bash java-codebase-rag increment --source-root /path/to/java/repo --index-dir /path/to/.java-codebase-rag --quiet diff --git a/plans/completed/CURSOR-PROMPTS-CLI-SCENARIOS.md b/plans/completed/CURSOR-PROMPTS-CLI-SCENARIOS.md index f25bf21..a347886 100644 --- a/plans/completed/CURSOR-PROMPTS-CLI-SCENARIOS.md +++ b/plans/completed/CURSOR-PROMPTS-CLI-SCENARIOS.md @@ -1,12 +1,12 @@ # Cursor task prompts — CLI scenarios (PR-CLI-1 → PR-CLI-3) Status: **active**. Implements -[`plans/PLAN-CLI-SCENARIOS.md`](./PLAN-CLI-SCENARIOS.md) and -[`propose/CLI-SCENARIOS-PROPOSE.md`](../propose/CLI-SCENARIOS-PROPOSE.md). +[`plans/completed/PLAN-CLI-SCENARIOS.md`](./PLAN-CLI-SCENARIOS.md) and +[`propose/completed/CLI-SCENARIOS-PROPOSE.md`](../propose/completed/CLI-SCENARIOS-PROPOSE.md). One prompt per PR. Each is **self-contained**: copy the prompt verbatim into Cursor, attach the files listed in its `@-files` block, and execute in agent -mode. If this prompt disagrees with **`plans/PLAN-CLI-SCENARIOS.md`**, the plan +mode. If this prompt disagrees with **`plans/completed/PLAN-CLI-SCENARIOS.md`**, the plan wins. **Workflow per PR** @@ -34,22 +34,22 @@ wins. **Branch:** `chore/cli-scenarios-propose-approval` off `master`. **Base:** `master`. -**Plan section:** `plans/PLAN-CLI-SCENARIOS.md` § PR-CLI-1. +**Plan section:** `plans/completed/PLAN-CLI-SCENARIOS.md` § PR-CLI-1. **Estimated diff size:** 1 file, ~10 LOC. **Attach (`@-files`):** -- `@plans/PLAN-CLI-SCENARIOS.md` (PR-CLI-1 section only) -- `@propose/CLI-SCENARIOS-PROPOSE.md` +- `@plans/completed/PLAN-CLI-SCENARIOS.md` (PR-CLI-1 section only) +- `@propose/completed/CLI-SCENARIOS-PROPOSE.md` **Prompt:** ```` -You are implementing PR-CLI-1 from `plans/PLAN-CLI-SCENARIOS.md`. +You are implementing PR-CLI-1 from `plans/completed/PLAN-CLI-SCENARIOS.md`. ## Scope -- Update `propose/CLI-SCENARIOS-PROPOSE.md` **status** from **draft** to **approved** +- Update `propose/completed/CLI-SCENARIOS-PROPOSE.md` **status** from **draft** to **approved** (or the repo’s equivalent convention) if reviewers have signed off. - Ensure **Appendix A** still states that the real issue URL is filled in **PR-CLI-2** (placeholder or canonical remote note — do not invent a final URL here). @@ -71,7 +71,7 @@ None (documentation only). ## Sentinel checks -- `git diff master --name-only` should list **only** `propose/CLI-SCENARIOS-PROPOSE.md` +- `git diff master --name-only` should list **only** `propose/completed/CLI-SCENARIOS-PROPOSE.md` (or be empty if already merged). ## Manual evidence @@ -92,16 +92,16 @@ N/A. **Branch:** `feat/cli-scenarios` off `master` (after PR-CLI-1 is on `master`, or stack if your team allows). **Base:** `master` (contains merged PR-CLI-1). -**Plan section:** `plans/PLAN-CLI-SCENARIOS.md` § PR-CLI-2 + **Resolved design +**Plan section:** `plans/completed/PLAN-CLI-SCENARIOS.md` § PR-CLI-2 + **Resolved design decisions** table. -**Propose:** `propose/CLI-SCENARIOS-PROPOSE.md` §3, §7, Appendix A (warning text). +**Propose:** `propose/completed/CLI-SCENARIOS-PROPOSE.md` §3, §7, Appendix A (warning text). **Estimated diff size:** ~25–40 files, large LOC (single atomic PR; prefer sequential commits per concern inside the branch). **Attach (`@-files`):** -- `@plans/PLAN-CLI-SCENARIOS.md` -- `@propose/CLI-SCENARIOS-PROPOSE.md` +- `@plans/completed/PLAN-CLI-SCENARIOS.md` +- `@propose/completed/CLI-SCENARIOS-PROPOSE.md` - `@user_rag/cli.py` (pre-rename; becomes `java_codebase_rag/cli.py`) - `@server.py` - `@java_index_flow_lancedb.py` @@ -122,10 +122,10 @@ sequential commits per concern inside the branch). **Prompt:** ```` -You are implementing PR-CLI-2 from `plans/PLAN-CLI-SCENARIOS.md`. +You are implementing PR-CLI-2 from `plans/completed/PLAN-CLI-SCENARIOS.md`. Read the **PR-CLI-2** section and the **Resolved design decisions** table in full. -Cross-check behaviour with `propose/CLI-SCENARIOS-PROPOSE.md` §3 / §7 / Appendix A. +Cross-check behaviour with `propose/completed/CLI-SCENARIOS-PROPOSE.md` §3 / §7 / Appendix A. If this prompt and the plan disagree, the plan wins. ## Scope @@ -274,14 +274,14 @@ production code paths must use the consolidated model. **Branch:** `chore/cli-scenarios-docs` off `master` (after PR-CLI-2 merged). **Base:** `master`. -**Plan section:** `plans/PLAN-CLI-SCENARIOS.md` § PR-CLI-3; propose §6 (doc list + +**Plan section:** `plans/completed/PLAN-CLI-SCENARIOS.md` § PR-CLI-3; propose §6 (doc list + acceptance grep + agent rules audit). **Estimated diff size:** ~15–25 files, mostly markdown. **Attach (`@-files`):** -- `@plans/PLAN-CLI-SCENARIOS.md` (PR-CLI-3 section) -- `@propose/CLI-SCENARIOS-PROPOSE.md` (§6) +- `@plans/completed/PLAN-CLI-SCENARIOS.md` (PR-CLI-3 section) +- `@propose/completed/CLI-SCENARIOS-PROPOSE.md` (§6) - `@README.md` - `@AGENTS.md` - `@CODEBASE_REQUIREMENTS.md` @@ -295,8 +295,8 @@ acceptance grep + agent rules audit). **Prompt:** ```` -You are implementing PR-CLI-3 from `plans/PLAN-CLI-SCENARIOS.md` and -`propose/CLI-SCENARIOS-PROPOSE.md` §6. +You are implementing PR-CLI-3 from `plans/completed/PLAN-CLI-SCENARIOS.md` and +`propose/completed/CLI-SCENARIOS-PROPOSE.md` §6. ## Scope diff --git a/plans/completed/PLAN-CLI-SCENARIOS.md b/plans/completed/PLAN-CLI-SCENARIOS.md index 641ae3e..71df8bb 100644 --- a/plans/completed/PLAN-CLI-SCENARIOS.md +++ b/plans/completed/PLAN-CLI-SCENARIOS.md @@ -1,8 +1,8 @@ # Plan: CLI scenarios — lifecycle verbs, config consolidation, naming -Status: **active**. This plan implements -[`propose/CLI-SCENARIOS-PROPOSE.md`](../propose/CLI-SCENARIOS-PROPOSE.md). -**PR-CLI-1** (propose approval + plan tracking) is [#72](https://github.com/HumanBean17/java-codebase-rag/pull/72); merge that PR to `master` to close the gate on mainline. +Status: **completed — shipped** to `master`. This plan implemented +[`propose/completed/CLI-SCENARIOS-PROPOSE.md`](../propose/completed/CLI-SCENARIOS-PROPOSE.md). +**PR-CLI-1** (propose approval + plan tracking) was [#72](https://github.com/HumanBean17/java-codebase-rag/pull/72). Depends on: **none** (engine work for Kuzu incremental rebuild stays under [`propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md`](../propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md) @@ -37,7 +37,7 @@ before PR-CLI-2 so contributors exercising new subcommands do not pay multi-seco **`CODEBASE_REQUIREMENTS.md`**, **`.cursor/rules/*.mdc`**, selected **`propose/*.md`**, **`mcp.json.example`** (comment polish only; keys land in PR-CLI-2), **`paper.pdf`** rebuild, plus **acceptance grep** / agent-rules audit per - [`propose/CLI-SCENARIOS-PROPOSE.md`](../propose/CLI-SCENARIOS-PROPOSE.md) §6. **PR-CLI-2** + [`propose/completed/CLI-SCENARIOS-PROPOSE.md`](../propose/completed/CLI-SCENARIOS-PROPOSE.md) §6. **PR-CLI-2** does **not** replace this: it ships code + `mcp.json.example` keys; a full doc sweep is explicitly **out of scope** for PR-CLI-2 (see PR-CLI-2 Definition of done). - **No ontology bump** and **no Kuzu / Lance schema changes** — this is operator @@ -71,7 +71,7 @@ before PR-CLI-2 so contributors exercising new subcommands do not pay multi-seco | PR | Scope | Ontology bump | Files touched (approx) | Test buckets | Independent of | | --- | --- | --- | --- | --- | --- | -| **PR-CLI-1** | Land / freeze propose (doc-only merge of `CLI-SCENARIOS-PROPOSE.md` if not already on `master`) | none | `propose/CLI-SCENARIOS-PROPOSE.md` (status bump); `plans/PLAN-CLI-SCENARIOS.md` (tracking) | n/a | none | +| **PR-CLI-1** | Land / freeze propose (doc-only merge of `CLI-SCENARIOS-PROPOSE.md` if not already on `master`) | none | `propose/completed/CLI-SCENARIOS-PROPOSE.md` (status bump); `plans/completed/PLAN-CLI-SCENARIOS.md` (tracking) | n/a | none | | **PR-CLI-2** | Full implementation: lifecycle handlers, env + YAML + index layout, package rename, `server.py` / indexer / path helpers, **`mcp_v2.py`**, **`path_filtering.py`** (`.lancedb-mcp/ignore` → `.java-codebase-rag/ignore`), help redesign, tracking issue constant, user-visible stderr hints; **`mcp.json.example`** env keys = source of truth | none | `pyproject.toml`, package dir rename, `server.py`, `mcp_v2.py`, `java_codebase_rag/cli.py`, `java_index_flow_lancedb.py`, `graph_enrich.py`, `path_filtering.py`, `search_lancedb.py`, `kuzu_queries.py`, `build_ast_graph.py`, tests, `mcp.json.example`, `.gitignore`, any other `user_rag` / env / path references in Python | unit + integration + help-structure test (see below) | PR-CLI-1 merged | | **PR-CLI-3** | Doc and example sweep + **`.cursor/rules/`** + migration sections + acceptance grep; **`mcp.json.example`** comment/example polish only (keys already correct from PR-CLI-2) | none | `README.md`, `docs/*`, `AGENTS.md`, `.cursor/rules/*.mdc`, `CODEBASE_REQUIREMENTS.md`, `mcp.json.example` (prose only if needed), selected `propose/*.md`, `.gitignore` notes | manual grep audit; `ruff` / `pytest` unchanged by docs | PR-CLI-2 merged | @@ -101,7 +101,7 @@ Landing order: **PR-CLI-1 → PR-CLI-2 → PR-CLI-3**. ## File-by-file changes -### 1. `propose/CLI-SCENARIOS-PROPOSE.md` +### 1. `propose/completed/CLI-SCENARIOS-PROPOSE.md` - Set status from **draft** to **approved** (or equivalent) once reviewers sign off. - Ensure Appendix A issue URL placeholder is clearly marked as filled in PR-CLI-2 @@ -121,7 +121,7 @@ Landing order: **PR-CLI-1 → PR-CLI-2 → PR-CLI-3**. | # | Step | File(s) | Done when | | --- | --- | --- | --- | -| 1 | Review & merge propose | `propose/CLI-SCENARIOS-PROPOSE.md`; plan tracking in this file | [#72](https://github.com/HumanBean17/java-codebase-rag/pull/72) merged to `master` | +| 1 | Review & merge propose | `propose/completed/CLI-SCENARIOS-PROPOSE.md`; plan tracking in this file | [#72](https://github.com/HumanBean17/java-codebase-rag/pull/72) merged to `master` | --- @@ -359,5 +359,5 @@ Add **Migration from legacy names** sections with explicit `mv` commands - `PR-CLI-1`: **done (awaiting `master` merge)** — [#72](https://github.com/HumanBean17/java-codebase-rag/pull/72) (propose **approved** + this plan’s tracking update) - `PR-CLI-2`: **implemented (awaiting merge to `master`)** — lifecycle CLI + config consolidation in tree -- `PR-CLI-3`: **in review** — `chore/cli-scenarios-docs`: README / docs / `AGENTS.md` / `.cursor/rules/` / migration / `paper.pdf` rebuild; mark **merged** when the PR lands on `master` (acceptance grep per `propose/CLI-SCENARIOS-PROPOSE.md` §6) +- `PR-CLI-3`: **in review** — `chore/cli-scenarios-docs`: README / docs / `AGENTS.md` / `.cursor/rules/` / migration / `paper.pdf` rebuild; mark **merged** when the PR lands on `master` (acceptance grep per `propose/completed/CLI-SCENARIOS-PROPOSE.md` §6) - `Kuzu incremental tracking issue`: **opened** — [#73](https://github.com/HumanBean17/java-codebase-rag/issues/73) (Tier 2 engine scope; URL matches `KUZU_INCREMENTAL_TRACKING_ISSUE_URL` in `java_codebase_rag/cli.py`) diff --git a/plans/PLAN-REPROCESS-SPLIT.md b/plans/completed/PLAN-REPROCESS-SPLIT.md similarity index 91% rename from plans/PLAN-REPROCESS-SPLIT.md rename to plans/completed/PLAN-REPROCESS-SPLIT.md index fa3a935..b3043a3 100644 --- a/plans/PLAN-REPROCESS-SPLIT.md +++ b/plans/completed/PLAN-REPROCESS-SPLIT.md @@ -1,7 +1,7 @@ # Plan: reprocess selective phase rebuild (`--vectors-only` / `--graph-only`) -Status: **active (planning)**. This plan implements -[`propose/REPROCESS-SPLIT-PROPOSE.md`](../propose/REPROCESS-SPLIT-PROPOSE.md). +Status: **completed — shipped** to `master`. This plan implemented +[`propose/completed/REPROCESS-SPLIT-PROPOSE.md`](../propose/completed/REPROCESS-SPLIT-PROPOSE.md). Depends on: **none**. @@ -136,19 +136,19 @@ Landing order: **RS1**. ## Definition of done (PR-RS1) -- [ ] `reprocess --help` shows mutually-exclusive selective flags. -- [ ] `--vectors-only` runs only cocoindex full reprocess path and never invokes graph builder. -- [ ] `--graph-only` runs only graph builder and never invokes cocoindex. -- [ ] Selective success emits one drift warning to stderr naming the non-rebuilt store. -- [ ] JSON payload includes `phases_run` with values matching phases actually spawned. -- [ ] Graph-only build failure exits with code `1` (not `2`). -- [ ] Selective setup failures exit with code `2`, emit no drift warning, and report +- [x] `reprocess --help` shows mutually-exclusive selective flags. +- [x] `--vectors-only` runs only cocoindex full reprocess path and never invokes graph builder. +- [x] `--graph-only` runs only graph builder and never invokes cocoindex. +- [x] Selective success emits one drift warning to stderr naming the non-rebuilt store. +- [x] JSON payload includes `phases_run` with values matching phases actually spawned. +- [x] Graph-only build failure exits with code `1` (not `2`). +- [x] Selective setup failures exit with code `2`, emit no drift warning, and report `phases_run=[]`. -- [ ] No-flag cocoindex failure reports `phases_run=["vectors"]` because graph was +- [x] No-flag cocoindex failure reports `phases_run=["vectors"]` because graph was not spawned. -- [ ] TTY pretty output for selective success includes `Rebuilt:` and `Skipped:`. -- [ ] No-flag `reprocess` lifecycle test remains green. -- [ ] `.venv/bin/python -m pytest tests/test_java_codebase_rag_cli.py -q` passes. +- [x] TTY pretty output for selective success includes `Rebuilt:` and `Skipped:`. +- [x] No-flag `reprocess` lifecycle test remains green. +- [x] `.venv/bin/python -m pytest tests/test_java_codebase_rag_cli.py -q` passes. ## Implementation step list @@ -160,6 +160,8 @@ Landing order: **RS1**. | 4 | Add/adjust CLI docs | `docs/JAVA-CODEBASE-RAG-CLI.md`, `README.md` | Docs match new CLI behavior, warning policy, argparse error shape, and default-vs-selective wording | | 5 | Add selective CLI tests | `tests/test_java_codebase_rag_cli.py` | New tests pass locally and anchor exit-code semantics | +All rows landed on `master` (PR-RS1). + --- # Cross-PR risks and mitigations @@ -197,4 +199,4 @@ Landing order: **RS1**. # Tracking -- `PR-RS1`: _pending_ +- `PR-RS1`: **landed** on `master` (selective `reprocess`, `phases_run`, docs, CLI tests). diff --git a/propose/INDEX-AUTO-MODE-PROPOSE.md b/propose/INDEX-AUTO-MODE-PROPOSE.md index f9ef55f..0caa6a4 100644 --- a/propose/INDEX-AUTO-MODE-PROPOSE.md +++ b/propose/INDEX-AUTO-MODE-PROPOSE.md @@ -1,6 +1,6 @@ # Proposal: Smart `refresh_code_index` Mode Selection -> **Note (2026):** the operator CLI’s full rebuild verb is now `java-codebase-rag reprocess` (see `propose/CLI-SCENARIOS-PROPOSE.md`); this MCP-side proposal still refers to `refresh_code_index` by name. +> **Note (2026):** the operator CLI’s full rebuild verb is now `java-codebase-rag reprocess` (see `propose/completed/CLI-SCENARIOS-PROPOSE.md`); this MCP-side proposal still refers to `refresh_code_index` by name. > > For embeddings or search over raw `propose/` text, expect both that historical MCP name and current CLI wording in the same document until this draft is implemented or archived under `propose/completed/`. diff --git a/propose/completed/CLI-SCENARIOS-PROPOSE.md b/propose/completed/CLI-SCENARIOS-PROPOSE.md index ac1e14f..42e5887 100644 --- a/propose/completed/CLI-SCENARIOS-PROPOSE.md +++ b/propose/completed/CLI-SCENARIOS-PROPOSE.md @@ -1,6 +1,6 @@ # CLI-SCENARIOS — restructure `java-codebase-rag` CLI, config, and naming -**Status**: approved — signed off for implementation via §6 (PR-CLI-2 / PR-CLI-3). +**Status**: completed — shipped (lifecycle verbs, config consolidation, package rename; plan closed under `plans/completed/PLAN-CLI-SCENARIOS.md`). **Author**: Dmitriy Teriaev + Perplexity Computer **Date**: 2026-05-10 diff --git a/propose/REPROCESS-SPLIT-PROPOSE.md b/propose/completed/REPROCESS-SPLIT-PROPOSE.md similarity index 99% rename from propose/REPROCESS-SPLIT-PROPOSE.md rename to propose/completed/REPROCESS-SPLIT-PROPOSE.md index 1671dac..e95b142 100644 --- a/propose/REPROCESS-SPLIT-PROPOSE.md +++ b/propose/completed/REPROCESS-SPLIT-PROPOSE.md @@ -1,6 +1,6 @@ # REPROCESS-SPLIT — Make `reprocess` selectively rebuild vectors and/or graph -**Status**: under review +**Status**: completed — shipped (`reprocess --vectors-only` / `--graph-only`, `phases_run`, drift warnings, docs, and CLI tests on `master`). **Author**: Dmitriy Teriaev + Perplexity Computer **Date**: 2026-05-12 (revised 2026-05-13 after review)