chore docs: drop stale migration callouts and directory-based propose/plan pointers (#138)

HumanBean17 · cursoragent · web-flow · commit d1476dc51d09 · 2026-05-15T22:38:29.000+03:00
Remove legacy on-disk rename/mv guidance from README and CLI guide; replace
enumerated plan/propose inventories in AGENTS.md and cursor rules with
directory layout. Generalize Cursor skills to use plans/completed patterns
and placeholder PR examples instead of fixed template filenames.

Co-authored-by: Cursor &lt;cursoragent@cursor.com&gt;
diff --git a/.cursor/rules/agent-workflow.mdc b/.cursor/rules/agent-workflow.mdc
@@ -12,13 +12,14 @@ inferring from code:
 
 - Behaviour / public surface → `README.md`.
 - Brownfield assumptions, role/capability tuning → `CODEBASE_REQUIREMENTS.md`.
+- In-flight design proposes → **`propose/*.md` at the root of `propose/`**
+  (not under `propose/completed/`). **List or search** for current names.
 - Why current design exists → `propose/completed/` and `plans/completed/`.
 - Testing philosophy → `tests/README.md`.
-- Currently-active plans → `plans/PLAN-POST-TIER1B-FOLLOWUPS.md`
-  (PR-E1 + PR-E2 — deferred catches from Tier 1B reviews). Recently
-  completed Tier 1B plans live under `plans/completed/` (see
-  `PLAN-TIER1B-COMPLETION.md` and `CURSOR-PROMPTS-TIER1B.md` as
-  reference templates).
+- In-flight multi-PR scope → **`plans/*.md` at the root of `plans/`**
+  (not under `plans/completed/`). Rule files are not a live catalog; **list
+  or search `plans/`** for active `PLAN-*.md` / `CURSOR-PROMPTS-*.md`.
+  Finished plans and prompt templates → `plans/completed/`.
 
 ## Propose-then-implement culture
 
diff --git a/.cursor/rules/project-overview.mdc b/.cursor/rules/project-overview.mdc
@@ -31,24 +31,16 @@ when needed.
 - `CODEBASE_REQUIREMENTS.md` — Java-repo assumptions and per-file
   map of what to edit when a target tree doesn't match defaults.
 - `tests/README.md` — testing philosophy.
-- `propose/` and `propose/completed/` — design proposes; the active
-  ones describe in-flight scope (currently
-  `TIER2-INCREMENTAL-REBUILD-PROPOSE.md` (paired with
-  `INDEX-AUTO-MODE-PROPOSE.md` — the decision engine
-  for the Kuzu rebuild path),
-  `RANKING-MICROSERVICE-PROPOSE.md`,
-  `ENHANCED-ROLE-RECOGNITION-PROPOSE.md`,
-  `DEFERRED-REST-CLIENT-MIGRATION-PROPOSE.md`,
-  `PRODUCT-VISION.md`) and the completed ones explain *why* current
-  code looks the way it does. Tier 1 + Tier 1B proposes
-  (`TIER1-COMPLETION-PROPOSE.md`, `TIER1B-HTTP-ASYNC-EDGES-PROPOSE.md`)
-  are now under `propose/completed/` since their PR sequences merged.
-- `plans/` and `plans/completed/` — longer-form plans (e.g.
-  capabilities model, tier completions, brownfield role overrides).
-  Active plan: `PLAN-POST-TIER1B-FOLLOWUPS.md` (deferred catches from
-  Tier 1B reviews). Completed Tier 1B plans + cursor-prompts
-  (`PLAN-TIER1B-COMPLETION.md`, `CURSOR-PROMPTS-TIER1B.md`) are kept
-  under `plans/completed/` as reference templates.
+- `propose/` — design proposes. **In-flight** proposes are **`*.md`
+  at the root of `propose/`** (not under `propose/completed/`).
+  **`propose/completed/`** — landed work and rationale for current code.
+  **List or search this tree** for current filenames; do not rely on
+  enumerated copies in rules.
+- `plans/` — longer-form multi-PR plans (`PLAN-*.md`) and
+  **`CURSOR-PROMPTS-*.md`** for per-PR Cursor handoffs. Top-level `*.md`
+  here are active or in-progress efforts. **`plans/completed/`** —
+  finished plans and completed prompt sets (templates). Same rule: **open
+  the directory**, don’t cache a mental file list from here.
 - `.cursor/rules/breaking-changes.mdc` — the no-back-compat policy.
 
 ## File map (top of repo)
diff --git a/.cursor/skills/plan-project-scope/SKILL.md b/.cursor/skills/plan-project-scope/SKILL.md
@@ -144,7 +144,7 @@ Each PR prompt should include:
 - pytest commands and evidence expectations (avoid hard totals that go stale)
 - definition of done and PR title convention
 
-Use `plans/completed/CURSOR-PROMPTS-TIER1B.md` as the structural reference.
+Use **any** completed **`plans/completed/CURSOR-PROMPTS-*.md`** as the structural reference (pick one that matches the effort’s shape).
 
 ## Naming and placement
 
diff --git a/.cursor/skills/plan-project-scope/reference.md b/.cursor/skills/plan-project-scope/reference.md
@@ -1,9 +1,6 @@
 # Plan Style Reference (Repo-grounded)
 
-This reference distills what made recent plan PRs strong:
-- `#39` (`plans/completed/PLAN-LIST-CLIENTS-MCP-TOOL.md`)
-- `#11` (`plans/PLAN-TIER1B-COMPLETION.md` + prompts file)
-- `#2` (`plans/PLAN-TIER1-COMPLETION.md`)
+This reference distills patterns from **merged multi-PR plans** in this repo. **Do not cache example filenames from here** — open **`plans/completed/`** (and root **`plans/`** for in-flight work) for current `PLAN-*.md` / `CURSOR-PROMPTS-*.md` examples; match their section depth and tables, not a particular PR number.
 
 ## Non-negotiables
 
diff --git a/.cursor/skills/plan-prompts/SKILL.md b/.cursor/skills/plan-prompts/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: plan-prompts
-description: Generate per-PR Cursor execution prompts in `plans/CURSOR-PROMPTS-*.md` from an existing `plans/PLAN-*.md`. Each prompt must include `## Tests to run (iteration loop)` (pytest file subset + rationales) between Deliverables and Tests per TEST-SUITE-FAST-LOOP. Use when the user asks to split implementation into Cursor-ready PR prompts with strict in-scope/out-of-scope guardrails.
+description: Generate per-PR Cursor execution prompts in `plans/CURSOR-PROMPTS-*.md` from an existing `plans/PLAN-*.md`. Each prompt must include `## Tests to run (iteration loop)` (pytest file subset + rationales) between Deliverables and Tests per the iteration convention in `tests/README.md`. Use when the user asks to split implementation into Cursor-ready PR prompts with strict in-scope/out-of-scope guardrails.
 disable-model-invocation: true
 ---
 
@@ -29,9 +29,10 @@ If already present in the plan, do not ask again.
 ## Source references to read
 
 Always read:
-1. `plans/completed/CURSOR-PROMPTS-TIER1B.md` (primary template)
-2. The target `plans/PLAN-*.md`
-3. `README.md` for current public contract terms when prompts mention tooling/schema
+1. **One** structural template from **`plans/completed/CURSOR-PROMPTS-*.md`** (pick a completed handoff similar in size or topic; if unsure, open the directory and choose any full example).
+2. The target **`plans/PLAN-*.md`**
+3. **`tests/README.md`** for merge gate + iteration-loop expectations
+4. **`README.md`** for current public contract terms when prompts mention tooling/schema
 
 ## Output file contract
 
@@ -59,7 +60,7 @@ Each PR prompt must include all of:
 
 ### Tests to run (iteration loop) — required subsection
 
-Per [`propose/completed/TEST-SUITE-FAST-LOOP-PROPOSE.md`](../../../propose/completed/TEST-SUITE-FAST-LOOP-PROPOSE.md) and [`plans/completed/PLAN-TEST-SUITE-FAST-LOOP.md`](../../../plans/completed/PLAN-TEST-SUITE-FAST-LOOP.md) PR-2:
+Per **`tests/README.md`** (iteration subset + where the `## Tests to run (iteration loop)` block lives). Background design history for the fast loop lives under **`propose/completed/`** and **`plans/completed/`** — search basenames for `TEST-SUITE` if you need the original PR wording.
 
 - Add a markdown section with the **exact heading** `## Tests to run (iteration loop)` inside the fenced **Prompt** block, **immediately after** `## Deliverables` and **before** `## Tests`.
 - Content: bullet list of `tests/test_*.py` paths, each with a **one-line rationale** tied to the PR’s code paths.
diff --git a/.cursor/skills/pr-open/pr-input.example.json b/.cursor/skills/pr-open/pr-input.example.json
@@ -1,39 +1,35 @@
 {
-  "title": "feat: retarget pass6 hint recovery to Client declarations (PR-LC2)",
+  "title": "feat: <short scope> (PR-Xn)",
   "base": "master",
   "draft": false,
-  "scope": "Implements PR-LC2 from `plans/completed/PLAN-LIST-CLIENTS-MCP-TOOL.md` by retargeting pass6 hint recovery to caller-side `Client` declarations.",
+  "scope": "Implements PR-Xn from `plans/PLAN-<TOPIC>.md` (or `plans/completed/PLAN-<TOPIC>.md` if the plan landed) by <one-sentence outcome>.",
   "what_changed": [
-    "Updated `build_ast_graph.py` pass6 fallback hint lookup to recover Feign hints from persisted `Client` rows.",
-    "Preserved existing `HTTP_CALLS(Symbol -> Route)` semantics and match outcomes.",
-    "Added `tests/test_client_hint_recovery.py` with focused continuity regressions."
+    "Example bullet: primary code path touched.",
+    "Example bullet: tests or fixtures added."
   ],
   "semantics_non_goals": [
-    "No LC3 MCP surface changes in this PR.",
-    "No broad LC1 schema redesign beyond consuming existing `Client` rows."
+    "Explicitly out-of-scope follow-ups for this PR."
   ],
   "validation": {
     "lint": [
       "`ruff check .` ✅"
     ],
     "tests": [
-      "`pytest tests/test_client_hint_recovery.py -v` ✅ (4 passed)",
-      "`pytest tests -v` ✅ (302 passed, 4 skipped)"
+      "`pytest tests/test_<area>.py -v` ✅",
+      "`pytest tests -v` ✅"
     ],
     "additional_checks": [
-      "`pytest tests/test_feign_not_exposer.py::test_feign_caller_resolves_to_target_endpoint tests/test_client_hint_recovery.py::test_find_route_callers_still_returns_expected_feign_caller -v` ✅"
+      "Optional focused pytest or `rg` spot-checks from the plan prompt."
     ]
   },
   "sentinel_checks": [
-    "`rg \"@mcp.tool\\(name=\\\"list_clients\\\"|ClientRowDto|ClientsListOutput\" server.py kuzu_queries.py` -> no matches ✅"
+    "`rg '<scope pattern>' <paths>` -> expected matches or silence ✅"
   ],
   "manual_evidence": [
-    "`python build_ast_graph.py --source-root tests/bank-chat-system --kuzu-path /tmp/check_lc2 --verbose`",
-    "Observed pass6 behavior remains stable with expected match breakdowns."
+    "Commands from the plan prompt, with expected stdout/stderr signals."
   ],
   "out_of_scope_confirmed": [
-    "LC3 MCP tool/DTO/docs (`list_clients`).",
-    "Route tool redesign or companion tools."
+    "Items the plan marks out of scope for this PR."
   ],
   "definition_of_done": [
     "All listed deliverables for this PR are shipped.",
diff --git a/.cursor/skills/propose/examples.md b/.cursor/skills/propose/examples.md
@@ -77,7 +77,7 @@ Add a first-class outbound declaration surface:
 
 ## PR body (proposal-only) template
 ## What
-Adds `propose/completed/LIST-CLIENTS-MCP-TOOL-PROPOSE.md` describing outbound client declarations and a new `list_clients` MCP tool.
+Adds `propose/completed/<TOPIC>-PROPOSE.md` (this sample used the list-clients topic) describing outbound client declarations and a new MCP tool surface.
 
 ## Why now
 Outbound declaration discovery needs a first-class tool after direction-honest annotation reshaping.
diff --git a/AGENTS.md b/AGENTS.md
@@ -11,42 +11,17 @@ for tools that don't read `.cursor/rules/`.
  MCP tool list (now `search` / `find` / `describe` / `neighbors`),
  CLI ops (`java-codebase-rag --help`), and "Re-index required" callouts.
  **`ontology_version` is currently 12** (HTTP brownfield rename + `CodebaseHttpMethod` enum + inbound HTTP layer-C replace; see README graph section).
-- [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) — operator guide for the `java-codebase-rag` CLI (`init` / `increment` / `reprocess` / `erase`, `meta`, `tables`, `diagnose-ignore`, `analyze-pr`; one-release hidden verb alias of `reprocess` with stderr deprecation only — see that doc).
+- [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) — operator guide for the `java-codebase-rag` CLI (`init` / `increment` / `reprocess` / `erase`, `meta`, `tables`, `diagnose-ignore`, `analyze-pr`; hidden `refresh` alias → `reprocess` — see that doc).
 - `CODEBASE_REQUIREMENTS.md` — Java-repo assumptions and tuning map.
-- `propose/` and `plans/` (plus their `completed/` subdirs) —
-  in-flight scope and the rationale behind current design.
-  - Active proposes: `TIER2-INCREMENTAL-REBUILD-PROPOSE.md` (Kuzu
-    diff-driven rebuild), `RANKING-MICROSERVICE-PROPOSE.md`,
-    `ENHANCED-ROLE-RECOGNITION-PROPOSE.md`,
-    `INDEX-AUTO-MODE-PROPOSE.md` (paired with TIER2 — decision engine for
-    incremental vs full),
-    `DEFERRED-REST-CLIENT-MIGRATION-PROPOSE.md`, `PRODUCT-VISION.md`.
-  - Active plans: `PLAN-POST-TIER1B-FOLLOWUPS.md` (PR-E1/PR-E2 —
-    deferred catches collected from PR-D1/D2/D3 reviews).
-  - Completed (Tier 1 + Tier 1B): `propose/completed/TIER1-COMPLETION-PROPOSE.md`,
-    `propose/completed/TIER1B-HTTP-ASYNC-EDGES-PROPOSE.md`,
-    `plans/completed/PLAN-TIER1-COMPLETION.md`,
-    `plans/completed/PLAN-TIER1B-COMPLETION.md`,
-    `plans/completed/CURSOR-PROMPTS-TIER1.md`,
-    `plans/completed/CURSOR-PROMPTS-TIER1B.md`. The two CURSOR-PROMPTS
-    files are kept as reference templates for future per-PR Cursor work.
-  - Older completed: `propose/completed/CALL-GRAPH-PROPOSE.md`,
-    `propose/completed/DESCRIBE-MEMBER-EDGE-ROLLUP-PROPOSE.md`,
-    `propose/completed/DESCRIBE-OVERRIDE-ROLLUP-PROPOSE.md`,
-    `plans/completed/PLAN-DESCRIBE-MEMBER-EDGE-ROLLUP.md`,
-    `plans/completed/PLAN-DESCRIBE-OVERRIDE-ROLLUP.md`,
-    `propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md` (four-tool MCP + `java-codebase-rag` CLI),
-    `plans/completed/PLAN-CALL-GRAPH.md`,
-    `plans/completed/PLAN-CAPABILITIES-MODEL.md`,
-    `plans/completed/PLAN-BROWNFIELD-ROLE-OVERRIDES.md`,
-    `plans/completed/PLAN-BROWNFIELD-ROLE-OVERRIDES-design-fixes.md`,
-    `plans/completed/PLAN-COCOINDEX-SYMLINK-FIX.md`,
-    `plans/completed/PLAN-ENUM-ANNOTATION-FIXES.md`,
-    `plans/completed/PLAN-REMOTE-PROJECT-INDEXING.md`,
-    `propose/completed/LIST-CLIENTS-MCP-TOOL-PROPOSE.md`,
-    `plans/completed/PLAN-LIST-CLIENTS-MCP-TOOL.md`,
-    `plans/completed/CURSOR-PROMPTS-LIST-CLIENTS-MCP-TOOL.md`. Read these
-    when you need the *why* behind current code.
+- **`propose/`** — design proposes. **In-flight** work is **`propose/*.md`**
+  (markdown at the root of `propose/` only, not under `completed/`).
+  **`propose/completed/`** — landed proposes and rationale. **List or search**
+  the tree for current filenames; entrypoint docs are not maintained as a
+  catalog.
+- **`plans/`** — multi-PR plans (`PLAN-*.md`) and per-PR Cursor prompts
+  (`CURSOR-PROMPTS-*.md`). Top-level files here are active or staged
+  multi-PR efforts; **`plans/completed/`** holds finished plans and
+  completed prompt sets (reference templates for future work).
 - `tests/README.md` — testing philosophy.
 
 Read these directly. Don't rely on rule files to mirror them.
@@ -118,10 +93,10 @@ When adding or editing Cypher run against Kuzu (for example in
 
 ## Per-PR Cursor task contract
 
-When picking up a per-PR Cursor task prompt (e.g. one of the entries
-under `plans/CURSOR-PROMPTS-<topic>.md`; see
-`plans/completed/CURSOR-PROMPTS-TIER1B.md` as the canonical reference
-template):
+When picking up a per-PR Cursor task prompt (from `plans/` or
+`plans/completed/`, files matching `CURSOR-PROMPTS-*.md`; use any
+completed prompt file in `plans/completed/` as a structural template
+when you need one):
 
 - Treat the prompt's **Out of scope** list as binding. Sentinel grep
   patterns in the prompt must return zero on `git diff master..HEAD`.
diff --git a/README.md b/README.md
@@ -15,7 +15,7 @@ The system extracts a deterministic property graph from Java source (tree-sitter
 
 For the design rationale, the GPS metaphor, and the full ontology, see [`docs/paper/paper.pdf`](./docs/paper/paper.pdf) (architecture report).
 
-> **Stability disclaimer.** This repo 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 re-index when the docs say to.
+> **Stability disclaimer.** This repo 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 (see [§6 Graph layer](#6-graph-layer)).
 
 ---
 
@@ -65,24 +65,7 @@ The operator-facing surface is **five** variables (plus MCP-only `JAVA_CODEBASE_
 
 Only the names in the table above (plus `JAVA_CODEBASE_RAG_SOURCE_ROOT` for MCP hosts) are read as configuration. Project config belongs in **`.java-codebase-rag.yml`** (or `.yaml`).
 
-### On-disk layout migration
-
-If you still have paths or files from older layout conventions:
-
-```bash
-# Default index directory (when you intend to keep the same data)
-mv lancedb_data .java-codebase-rag
-
-# Project YAML (only `.java-codebase-rag.yml` / `.yaml` are loaded)
-mv .lancedb-mcp.yml .java-codebase-rag.yml
-# or: mv .lancedb-mcp.yaml .java-codebase-rag.yaml
-
-# Layered ignore directory (same gitignore-style rules; new location only)
-mkdir -p .java-codebase-rag
-mv .lancedb-mcp/ignore .java-codebase-rag/ignore   # if you had a project-level ignore file
-```
-
-**Where things live today** (for scripts and operators):
+**Paths and conventions** (for scripts and operators):
 
 - **`JAVA_CODEBASE_RAG_INDEX_DIR`** — filesystem path to the index directory (not a URI). Lance opens this directory; Kuzu is always `<index-dir>/code_graph.kuzu`; cocoindex keeps **`cocoindex.db`** next to them.
 - **Java tree root** — CLI: `--source-root` (else cwd). MCP stdio: set `JAVA_CODEBASE_RAG_SOURCE_ROOT` when the Java repo root differs from the server process cwd.
@@ -91,13 +74,9 @@ mv .lancedb-mcp/ignore .java-codebase-rag/ignore   # if you had a project-level
 
 Python package: **`java_codebase_rag`** (`python -m java_codebase_rag.cli`).
 
-**Operator note:** the hidden CLI verb **`refresh`** invokes **`reprocess`** and prints a one-line stderr deprecation; call **`reprocess`** in new scripts.
-
-If an old on-disk index folder is wasting space, relocate or delete it after your data lives under `.java-codebase-rag/` (some installs used a top-level directory named `lancedb_data`).
-
 ### Project YAML reference (`.java-codebase-rag.yml`)
 
-A single file at the project root (the directory you pass as `--source-root`, or cwd) holds everything that isn't an environment variable. The two accepted filenames are `.java-codebase-rag.yml` and `.java-codebase-rag.yaml`; if both exist, `.yml` wins. Legacy `.lancedb-mcp.yml` is no longer read.
+A single file at the project root (the directory you pass as `--source-root`, or cwd) holds everything that isn't an environment variable. The two accepted filenames are `.java-codebase-rag.yml` and `.java-codebase-rag.yaml`; if both exist, `.yml` wins.
 
 **All keys are optional.** A project with no YAML at all uses built-in defaults plus env vars. Add only the keys you need.
 
@@ -300,7 +279,7 @@ Shared flags on all subcommands: `--source-root`, `--index-dir`, `--embedding-mo
 | Introspection | `meta`, `tables`, `diagnose-ignore` | Health, table listing, ignore-layer diagnostics. |
 | Analysis | `analyze-pr` | Blast-radius / risk from a unified diff. |
 
-The hidden alias `refresh` → `reprocess` prints a one-line stderr deprecation; prefer `reprocess` in scripts.
+The hidden alias **`refresh`** invokes **`reprocess`** (prefer **`reprocess`** in new scripts).
 
 Examples:
 
diff --git a/docs/JAVA-CODEBASE-RAG-CLI.md b/docs/JAVA-CODEBASE-RAG-CLI.md
@@ -40,25 +40,7 @@ java-codebase-rag meta --source-root /path/to/java/repo --index-dir /path/to/.ja
 
 **Precedence** (when a knob exists in more than one place): **CLI flag > env var > YAML (`.java-codebase-rag.yml`) > built-in default**.
 
-Only the variable names in the table above are read as configuration. Rename on-disk config with:
-
-```bash
-mv .lancedb-mcp.yml .java-codebase-rag.yml
-# or: mv .lancedb-mcp.yaml .java-codebase-rag.yaml
-```
-
-If you still have data under `lancedb_data/` and want a single index dir:
-
-```bash
-mv lancedb_data .java-codebase-rag
-```
-
-Move layered ignore files the same way:
-
-```bash
-mkdir -p .java-codebase-rag
-mv .lancedb-mcp/ignore .java-codebase-rag/ignore
-```
+Only the variable names in the table above are read as configuration.
 
 ## Shared flags
 
@@ -149,7 +131,7 @@ java-codebase-rag erase --source-root /path/to/java/repo --index-dir /path/to/.j
 
 ### Hidden `refresh` alias
 
-Invoking `java-codebase-rag refresh` runs **`reprocess`** and prints a one-line **stderr** deprecation warning. Prefer **`reprocess`** in scripts.
+`java-codebase-rag refresh` runs **`reprocess`**. Prefer **`reprocess`** in scripts.
 
 ## Introspection subcommands
 
@@ -232,6 +214,6 @@ Prefer **`java-codebase-rag reprocess --graph-only`** when you only need Kuzu re
 
 ## See also
 
-- [README.md](../README.md) — env vars, MCP tool table, ignore layout, migration table.
+- [README.md](../README.md) — env vars, MCP tool table, ignore layout.
 - [CODEBASE_REQUIREMENTS.md](../CODEBASE_REQUIREMENTS.md) — repo layout, brownfield, when to rebuild.
 - [MANUAL-VERIFICATION-CHECKLIST.md](./MANUAL-VERIFICATION-CHECKLIST.md) — phased checks that mix CLI + MCP.
diff --git a/docs/skills/java-codebase-explore.md b/docs/skills/java-codebase-explore.md
