chore: cleanup proposals, plans, and reports folder structure

AGENTS.md

@@ -39,7 +39,7 @@ when needed.
   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 per-file map of
+- `docs/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/`** — design proposes. **In-flight** proposes are **`*.md`
@@ -112,7 +112,7 @@ For any non-trivial change, read the relevant doc first instead of
 inferring from code:
 
 - Behaviour / public surface → `README.md`.
-- Brownfield assumptions, role/capability tuning → `CODEBASE_REQUIREMENTS.md`.
+- Brownfield assumptions, role/capability tuning → `docs/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/`.

README.md

@@ -128,7 +128,7 @@ The operator-facing surface is small: pick an index dir, pick an embedding model
 | Understand the graph (nodes, edges, capabilities, ranking) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §3 |
 | Steer a brownfield Java tree (custom stereotypes, non-Spring stacks) | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §4 |
 | Control which files the indexer walks | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) §5 |
-| Check whether your repo fits this tool's assumptions | [`CODEBASE_REQUIREMENTS.md`](./CODEBASE_REQUIREMENTS.md) |
+| Check whether your repo fits this tool's assumptions | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) |
 
 ---
 
@@ -158,9 +158,9 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi
 | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. |
 | [`docs/skills/java-codebase-explore.md`](./docs/skills/java-codebase-explore.md) | Agent exploration skill (strategy, missions, fallbacks); packaged zip [`docs/skills/java-codebase-explore.zip`](./docs/skills/java-codebase-explore.zip) for Perplexity-style hosts. |
 | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. |
-| [`CODEBASE_REQUIREMENTS.md`](./CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. |
+| [`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). |
-| [`propose/PRODUCT-VISION.md`](./propose/PRODUCT-VISION.md) | Long-term product direction. |
+| [`docs/PRODUCT-VISION.md`](./docs/PRODUCT-VISION.md) | Long-term product direction. |
 
 ---
 

CODEBASE_REQUIREMENTS.md → docs/CODEBASE_REQUIREMENTS.md

@@ -173,7 +173,7 @@ and `capabilities`, register inbound routes, and register outbound
 clients/producers for a given repo via `.java-codebase-rag.yml` at the project
 root (`role_overrides:`, `route_overrides:`, `http_client_overrides:`,
 `async_producer_overrides:`) and/or by copying the in-source stubs from
-[`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) into your sources:
+[`docs/CONFIGURATION.md`](./CONFIGURATION.md) into your sources:
 
 - `@CodebaseRole` / `@CodebaseCapability` / `@CodebaseCapabilities`
   (class-level role + capabilities) — see `docs/CONFIGURATION.md` §4.3.

docs/JAVA-CODEBASE-RAG-CLI.md

@@ -226,5 +226,5 @@ 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.
-- [CODEBASE_REQUIREMENTS.md](../CODEBASE_REQUIREMENTS.md) — repo layout, brownfield, when to rebuild.
+- [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.

plans/completed/AGENT-PROMPTS-MCP-API-V2.md

@@ -279,7 +279,7 @@ Headline items:
 2. `README.md`: delete v1 tool reference; promote "v2 navigation tools
    (preview)" to primary `### Tool reference`. Keep ops tools listed as
    "operational — moving to `user-rag` CLI in next release".
-3. `propose/PRODUCT-VISION.md`: rewrite v1 example invocations to v2 (per
+3. `docs/PRODUCT-VISION.md`: rewrite v1 example invocations to v2 (per
    propose §11 mapping).
 4. Delete `tests/test_mcp_v2_equivalence.py` entirely — v1 no longer exists.
 5. Update `tests/test_server.py` (or add if missing) tool-count assertion to:
@@ -322,9 +322,9 @@ grep -nE "^### Tool reference" README.md
 - [ ] `tests/test_mcp_v2_equivalence.py` does not exist.
 - [ ] README §"Tool reference" lists exactly the 4 v2 tools as primary; ops
       tools noted as transitional.
-- [ ] `propose/PRODUCT-VISION.md` example invocations updated to v2.
+- [ ] `docs/PRODUCT-VISION.md` example invocations updated to v2.
 - [ ] Diff is confined to deliverables in this prompt (`server.py`, `README.md`,
-      `propose/PRODUCT-VISION.md`, deleted `tests/test_mcp_v2_equivalence.py`,
+      `docs/PRODUCT-VISION.md`, deleted `tests/test_mcp_v2_equivalence.py`,
       `tests/test_server.py` or equivalent surface-assertion test), plus
       narrowly-related test harness/import updates required to make those
       changes pass.
@@ -337,7 +337,7 @@ grep -nE "^### Tool reference" README.md
 - [`plans/PLAN-MCP-API-V2.md` § PR-V2-3](./PLAN-MCP-API-V2.md#pr-v2-3--delete-v1-navigation-tools)
   — list of the 18 tools to delete.
 - [`propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md`](../../propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md)
-  §11 mapping table — for rewriting `propose/PRODUCT-VISION.md` examples.
+  §11 mapping table — for rewriting `docs/PRODUCT-VISION.md` examples.
 - `server.py` history (git log) — to identify each tool's helper-function
   graveyard.
 

plans/completed/AGENT-PROMPTS-TIER1B.md

@@ -575,7 +575,7 @@ Concretely:
   plan §5.3) — two services + a third "ambiguous" controller.
 - Create `tests/test_call_edge_matching.py` with cases 32–40.
 - Extend `tests/test_mcp_tools.py` with cases 41–48.
-- Flip `propose/PRODUCT-VISION.md` `HTTP_CALLS` / `ASYNC_CALLS` rows
+- Flip `docs/PRODUCT-VISION.md` `HTTP_CALLS` / `ASYNC_CALLS` rows
   from *planned* to *shipped*.
 
 ## Out of scope (do NOT touch)
@@ -620,7 +620,7 @@ don't ship it.
 11. New fixture `tests/fixtures/cross_service_smoke/`.
 12. New test file `tests/test_call_edge_matching.py` with cases 32–40.
 13. Cases 41–48 added to `tests/test_mcp_tools.py`.
-14. `propose/PRODUCT-VISION.md` flipped (planned → shipped).
+14. `docs/PRODUCT-VISION.md` flipped (planned → shipped).
 15. `README.md` MCP tools section updated.
 
 ## Tests
@@ -681,7 +681,7 @@ Expected: at least one caller from `chat-assign` with `match='cross_service'`.
 - [ ] Sentinel greps return expected results.
 - [ ] No file outside `build_ast_graph.py`, `kuzu_queries.py`,
       `server.py`, `pr_analysis.py`, `README.md`,
-      `propose/PRODUCT-VISION.md`, and the new `tests/` paths is
+      `docs/PRODUCT-VISION.md`, and the new `tests/` paths is
       modified.
 - [ ] PR description includes the scope statement, the manual evidence
       output (pass6 log + meta() snippet + find_route_callers output),

plans/completed/PLAN-BROWNFIELD-ROLE-OVERRIDES-design-fixes.md

@@ -6,7 +6,7 @@ Status: **completed** — applied. Companion document to
 ## Why this file exists
 
 The brownfield plan grew through two review rounds; the second review
-(`reports/review/active/PLAN-BROWNFIELD-ROLE-OVERRIDES-design-issues.md`)
+(`docs/reports/review/completed/PLAN-BROWNFIELD-ROLE-OVERRIDES-design-issues.md`)
 flagged design issues that were folded back into the plan in-place.
 Once they're inlined, they stop standing out — but they are exactly
 the parts an implementer is most likely to skim past or get wrong,

plans/completed/PLAN-BROWNFIELD-ROLE-OVERRIDES.md

@@ -805,7 +805,7 @@ order in this list is the only correct interleaving; do not reorder.
 - `README.md` — new section "Brownfield overrides" walking through Layer
   B (config), with a complete example block. Mention Layer C as the last
   resort, with the four interface declarations to copy-paste.
-- `CODEBASE_REQUIREMENTS.md` — expand the role-inference section to note
+- `docs/CODEBASE_REQUIREMENTS.md` — expand the role-inference section to note
   the override layers exist.
 - MCP server `instructions` string in `server.py` — one extra sentence
   noting that "role and capability inference can be customised per-project

plans/completed/PLAN-CALL-GRAPH.md

@@ -460,7 +460,7 @@ Additions (~80 lines, no removals):
    - How to filter by `min_confidence`.
    - Why phantoms aren't dropped at index time.
 
-### 8. `CODEBASE_REQUIREMENTS.md`
+### 8. `docs/CODEBASE_REQUIREMENTS.md`
 
 Add a "Call graph" note listing the tree-sitter node types the extractor
 depends on:
@@ -585,7 +585,7 @@ Single PR. Breaking changes:
 | 8 | Augment `_graph_expand_merge` to also call `expand_methods`. | `search_lancedb.py` | Graph-expand results include method-reachable chunks on the smoke corpus. |
 | 9 | Add MCP tools (`find_callers`, `find_callees`), `follow_calls` param on `trace_flow`, update `_INSTRUCTIONS`. | `server.py` | `test_mcp_tools.py` additions pass. |
 | 10 | Update tests: new files + extend `test_ast_graph_build.py` / `test_kuzu_queries.py` / `test_mcp_tools.py`. | `tests/` | `pytest` green. |
-| 11 | Update `README.md` + `CODEBASE_REQUIREMENTS.md`. | docs | Manual review. |
+| 11 | Update `README.md` + `docs/CODEBASE_REQUIREMENTS.md`. | docs | Manual review. |
 | 12 | Confirm `propose/completed/CALL-GRAPH-PROPOSE.md` is the only active call-graph proposal (old deferred draft already removed; git history retains it). | `propose/` | Directory listing shows a single call-graph proposal. |
 
 ## Out of scope (for this plan, tracked elsewhere)

plans/completed/PLAN-CAPABILITIES-MODEL.md

@@ -453,7 +453,7 @@ callers see them in results.
 - `README.md` — add a section "Capabilities" describing the multi-tag
   axis, the initial capability set, and `list_by_capability`. Keep the
   existing "Roles" section intact.
-- `CODEBASE_REQUIREMENTS.md` — note the type-level granularity choice
+- `docs/CODEBASE_REQUIREMENTS.md` — note the type-level granularity choice
   and the deferred per-method storage (link to this plan).
 - MCP server `instructions` string in `server.py` — one extra sentence
   pointing at `list_by_capability` for behavioural questions about

plans/completed/PLAN-CLI-SCENARIOS.md

@@ -73,7 +73,7 @@ before PR-CLI-2 so contributors exercising new subcommands do not pay multi-seco
 | --- | --- | --- | --- | --- | --- |
 | **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 |
+| **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`, `docs/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 |
 
 Landing order: **PR-CLI-1 → PR-CLI-2 → PR-CLI-3**.
 
@@ -284,7 +284,7 @@ Follow the **explicit file list** in propose §6 (`README.md`,
 `paper.pdf`, `AGENTS.md`, **`.cursor/rules/*.mdc`** (agent rules audit),
 `CODEBASE_REQUIREMENTS.md`, `mcp.json.example` (comments only — keys from PR-CLI-2),
 `propose/INDEX-AUTO-MODE-PROPOSE.md`,
-`propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md`, `propose/PRODUCT-VISION.md`,
+`propose/TIER2-INCREMENTAL-REBUILD-PROPOSE.md`, `docs/PRODUCT-VISION.md`,
 `.gitignore`).
 
 Add **Migration from legacy names** sections with explicit `mv` commands
@@ -314,7 +314,7 @@ Add **Migration from legacy names** sections with explicit `mv` commands
 | # | Step | File(s) | Done when |
 | --- | --- | --- | --- |
 | 1 | README + CLI operator guide | `README.md`, `docs/JAVA-CODEBASE-RAG-CLI.md` | New subcommand table + 5 env vars + migration |
-| 2 | Agent + checklist + requirements | `docs/*`, `CODEBASE_REQUIREMENTS.md` | No stale operator paths |
+| 2 | Agent + checklist + requirements | `docs/*`, `docs/CODEBASE_REQUIREMENTS.md` | No stale operator paths |
 | 3 | Paper + proposes + example MCP JSON | `docs/paper/`, `propose/*`, `mcp.json.example` | PDF rebuilt; examples updated |
 | 4 | Acceptance grep | repo root | Reviewer sign-off |
 

plans/completed/PLAN-CLIENT-ROLE-RENAME.md

@@ -188,7 +188,7 @@ Six references at `server.py:49, 689, 1141, 1338, 1342, 1418`:
 - Line 1342: docstring `"...FEIGN_CLIENT/REPOSITORY/MAPPER..."` → `"...CLIENT/REPOSITORY/MAPPER..."`
 - Line 1418: `entry_roles = ["CONTROLLER", "COMPONENT", "SERVICE", "FEIGN_CLIENT"]` → `[..., "CLIENT"]`
 
-#### Change 6: Update `README.md` and `CODEBASE_REQUIREMENTS.md`
+#### Change 6: Update `README.md` and `docs/CODEBASE_REQUIREMENTS.md`
 
 `README.md`:
 - Line 137: `trace_flow` description's stage chain `FEIGN_CLIENT/REPOSITORY/MAPPER` → `CLIENT/REPOSITORY/MAPPER`
@@ -338,7 +338,7 @@ description.
 - [ ] `_ROLE_SCORE_WEIGHTS["CLIENT"] = 0.06` (was `FEIGN_CLIENT`) (`search_lancedb.py:188`)
 - [ ] Six `server.py` literal references updated (lines 49, 689, 1141, 1338, 1342, 1418)
 - [ ] `README.md` updated (3 lines + brownfield note)
-- [ ] `CODEBASE_REQUIREMENTS.md` updated (lines 146, 162, 346-347)
+- [ ] `docs/CODEBASE_REQUIREMENTS.md` updated (lines 146, 162, 346-347)
 - [ ] `tests/test_lancedb_e2e.py:342` allow-list updated
 - [ ] `ONTOLOGY_VERSION` bumped 8 → 9 with phase-comment update
 - [ ] All 9 new tests in `tests/test_client_role_rename.py` pass

plans/completed/PLAN-HTTP-ROUTE-METHOD-ENUM.md

@@ -31,7 +31,7 @@ Depends on: **none** (lands on current `master`).
 | PR | Scope | Ontology bump | Files touched (approx) | Test buckets | Independent of |
 | --- | --- | --- | --- | --- | --- |
 | **PR-1** | `CodebaseHttpMethod.java` stub under route fixtures; **parameterized** structured stderr emitter (new small module and/or `build_ast_graph.py`) — **no production call sites** | **none** | `tests/fixtures/brownfield_route_stubs/...`, emitter module, **1** new test | Unit test exercises emitter directly (INFO + WARN shapes as needed) | none |
-| **PR-2** | Rename stubs + route stub field type; `ast_java.py` recognition + client `method` enum parse + **extractor-time** INFO shadowing + WARN on string `method`; `graph_enrich.py` HTTP branch replace **without** merge-time shadowing + `meta_chain` / log strings; tighten `test_23`; **new** inbound exclusivity test; README + `CODEBASE_REQUIREMENTS.md` + any other doc hits for examples | **11 → 12** (`ast_java.ONTOLOGY_VERSION`; README / `AGENTS.md` callouts) | `ast_java.py`, `graph_enrich.py`, structured-log module (see PR-2 §4), stubs, `tests/test_*.py` listed below, `README.md`, `CODEBASE_REQUIREMENTS.md`, `build_ast_graph.py` if comment at ~1904 | Full `pytest tests`; new exclusivity + optional shadowing log test | PR-1 merged |
+| **PR-2** | Rename stubs + route stub field type; `ast_java.py` recognition + client `method` enum parse + **extractor-time** INFO shadowing + WARN on string `method`; `graph_enrich.py` HTTP branch replace **without** merge-time shadowing + `meta_chain` / log strings; tighten `test_23`; **new** inbound exclusivity test; README + `docs/CODEBASE_REQUIREMENTS.md` + any other doc hits for examples | **11 → 12** (`ast_java.ONTOLOGY_VERSION`; README / `AGENTS.md` callouts) | `ast_java.py`, `graph_enrich.py`, structured-log module (see PR-2 §4), stubs, `tests/test_*.py` listed below, `README.md`, `docs/CODEBASE_REQUIREMENTS.md`, `build_ast_graph.py` if comment at ~1904 | Full `pytest tests`; new exclusivity + optional shadowing log test | PR-1 merged |
 | **PR-3** | Agent docs + v2 addendum only | **none** | `docs/AGENT-GUIDE.md`, `docs/skills/java-codebase-explore.md` (if needed), `propose/completed/BROWNFIELD-ANNOTATIONS-V2-ADDENDUM-HTTP-METHOD-ENUM.md` | Docs-only CI | PR-2 merged |
 
 Landing order: **PR-1 → PR-2 → PR-3**.
@@ -136,7 +136,7 @@ Landing order: **PR-1 → PR-2 → PR-3**.
 - `tests/test_assign_endpoint_client_extraction.py` — Feign + JAX-RS mirror; `method = HttpMethod.POST` may need alignment with **`CodebaseHttpMethod.POST`** on brownfield annotation per surface rules.
 - `tests/test_cross_service_resolution_flag.py` — generated Java strings.
 
-### 8. `README.md` and `CODEBASE_REQUIREMENTS.md`
+### 8. `README.md` and `docs/CODEBASE_REQUIREMENTS.md`
 
 - Replace annotation names and examples with `@CodebaseHttpClient` / enum `method`; add **Re-index required** callout for PR-2 + ontology **12**.
 
@@ -185,7 +185,7 @@ Landing order: **PR-1 → PR-2 → PR-3**.
 | 3 | Merge HTTP replace (behaviour only) | `graph_enrich.py` | Replace pattern; **zero** shadowing logs from this file |
 | 4 | Verbose plumbing if needed | `build_ast_graph.py` → parse entry | Shadowing INFO respects volume gate |
 | 5 | `meta_chain` + log strings | `graph_enrich.py` | Grep clean for old simple names |
-| 6 | Tests + docs | `tests/*`, `README.md`, `CODEBASE_REQUIREMENTS.md` | Full pytest; doc examples match stubs |
+| 6 | Tests + docs | `tests/*`, `README.md`, `docs/CODEBASE_REQUIREMENTS.md` | Full pytest; doc examples match stubs |
 | 7 | Ontology + meta test | `ast_java.py`, `tests/test_call_edges_e2e.py` | `meta()` reports 12 |
 
 ---