address pr 155 review: lock traversals and member_only contracts

Clarify role-keyed typical_traversals vs SCHEMA appendix tuples, split
member_only across PR-A/PR-C, update PROPOSES-ORDER phase 2, and align
prompts with pr_analysis and compose test coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: HumanBean17

docs/PROPOSES-ORDER.md

@@ -13,7 +13,7 @@ When two or more proposes touch overlapping subsystems, the order they lock and
 
 1. **SCHEMA-V2** — `propose/SCHEMA-V2-PROPOSE.md` (propose merged via [#151](https://github.com/HumanBean17/java-codebase-rag/pull/151); treat as locked for sequencing)
    - 4 code PRs: PR-A (`EDGE_SCHEMA` + ontology v14 bump), PR-B (`HTTP_CALLS` flip + downstream API), PR-C (`Producer` node + `ASYNC_CALLS` flip + GraphMeta + MCP parity), PR-D (hints v3).
-2. **HINTS-V3** — `propose/HINTS-V3-PROPOSE.md` ([#154](https://github.com/HumanBean17/java-codebase-rag/pull/154), draft)
+2. **HINTS-V3** — `propose/HINTS-V3-PROPOSE.md` (merged [#154](https://github.com/HumanBean17/java-codebase-rag/pull/154); set `Status: locked` before PR-D)
    - Implementation = SCHEMA-V2 PR-D (same PR).
 
 No other proposes are in flight.
@@ -35,17 +35,17 @@ HINTS-V3-PROPOSE.md    [draft PR #154 — SCHEMA-V2 Decision 30]
 ### Phase 2 — plan + cursor-prompt artefacts
 
 ```
-plans/PLAN-SCHEMA-V2.md          [not started]
+plans/PLAN-SCHEMA-V2.md          [landed #155]
 plans/CURSOR-PROMPTS-SCHEMA-V2.md
 plans/PLAN-HINTS-V3.md
 plans/CURSOR-PROMPTS-HINTS-V3.md
 ```
 
-SCHEMA-V2 Decision 29: `PLAN-SCHEMA-V2.md` + `CURSOR-PROMPTS-SCHEMA-V2.md` are merge gates for **PR-A**.
+SCHEMA-V2 Decision 29: `PLAN-SCHEMA-V2.md` + `CURSOR-PROMPTS-SCHEMA-V2.md` are merge gates for **PR-A** (satisfied when [#155](https://github.com/HumanBean17/java-codebase-rag/pull/155) is on `master`).
 
-By analogy: `PLAN-HINTS-V3.md` + `CURSOR-PROMPTS-HINTS-V3.md` are merge gates for **PR-D**.
+By analogy: `PLAN-HINTS-V3.md` + `CURSOR-PROMPTS-HINTS-V3.md` are merge gates for **PR-D** (same PR).
 
-Plans and prompts may be drafted in parallel with each other; each pair must land before its code PR.
+Plans and prompts may be drafted in parallel with each other; each pair must land before its code PR. **Code PRs (Phase 3) are not started** until Phase 2 is on `master`.
 
 ### Phase 3 — code PRs (merge order)
 

plans/CURSOR-PROMPTS-SCHEMA-V2.md

@@ -48,7 +48,7 @@ Read PR-A **File-by-file changes** and **Tests for PR-A** before coding. Plan wi
 
 ## Scope
 
-1. **`java_ontology.py`** — `EdgeAttr`, `EdgeSpec`, `EDGE_SCHEMA` for **10 edges** with **pre-flip** `HTTP_CALLS`/`ASYNC_CALLS` (`Symbol→Route`). Include `brownfield_resolver_sourced`, role-keyed `typical_traversals`, `member_only` per HINTS-V3 §3.4. Add `BROWNFIELD_RESOLVER_STRATEGY_SET` (union of `FUZZY_STRATEGY_SET` + resolver strategies used on edges today).
+1. **`java_ontology.py`** — `EdgeAttr`, `EdgeSpec`, `EDGE_SCHEMA` for **10 edges** with **pre-flip** `HTTP_CALLS`/`ASYNC_CALLS` (`Symbol→Route`). Include `brownfield_resolver_sourced`; **`typical_traversals: dict[str, str]`** per HINTS-V3 §3.5 (SCHEMA propose Appendix A tuples are illustrative only). **`member_only`:** set `True` on `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`, `CALLS` only — **not** `DECLARES_PRODUCER` (PR-C). Add `BROWNFIELD_RESOLVER_STRATEGY_SET` (union of `FUZZY_STRATEGY_SET` + resolver strategies used on edges today); **enumerate every member in the PR body**.
 2. **`scripts/generate_edge_navigation.py`** + committed **`docs/EDGE-NAVIGATION.md`** with `--check` mode.
 3. **`ast_java.py`** — `ONTOLOGY_VERSION = 14`.
 4. **`README.md`** + **`docs/AGENT-GUIDE.md`** — v14 re-index callout (PR-B/C consequences one sentence each).
@@ -125,6 +125,7 @@ Before PR open:
 - `@tests/test_pr_analysis.py`
 - `@tests/test_brownfield_clients.py`
 - `@tests/test_mcp_v2.py`
+- `@tests/test_mcp_v2_compose.py`
 - `@tests/test_client_hint_recovery.py`
 
 **Prompt:**
@@ -196,6 +197,7 @@ Before PR open: `.venv/bin/ruff check .` and `.venv/bin/python -m pytest tests -
 - `@java_ontology.py`
 - `@build_ast_graph.py`
 - `@kuzu_queries.py`
+- `@pr_analysis.py`
 - `@mcp_v2.py`
 - `@server.py`
 - `@tests/test_call_edges_e2e.py`
@@ -217,10 +219,12 @@ PR-B is on `master` (HTTP_CALLS from Client). Do not revert HTTP shape.
 2. **`AsyncCallRow.producer_id`**; Producer fields from `AsyncProducerHint` / dispatch metadata (propose §3.2 table — no HTTP-only copy-paste).
 3. **`GraphMeta`**: `producers_total`, `declares_producer_total`; wire `server.py` meta output if applicable.
 4. **`kuzu_queries.py`**: async two-hop in `find_route_callers`, `trace_request_flow`, impact analysis; producer branch on `RouteCaller`.
-5. **`mcp_v2.py`**: `find(kind="producer")`, `resolve(hint_kind="producer")`, `_load_node_record` for Producer.
-6. **Type-level `describe` rollups**: `DECLARES.DECLARES_PRODUCER`, `OVERRIDDEN_BY.DECLARES_PRODUCER`.
-7. **Async doc sweep** + regenerate `docs/EDGE-NAVIGATION.md` (11 edges).
-8. **Tests** — All **Tests for PR-C** in the plan (verbatim).
+5. **`pr_analysis.py`**: async two-hop route reachability (`DECLARES_PRODUCER` + `ASYNC_CALLS`; HTTP already two-hop from PR-B).
+6. **`mcp_v2.py`**: `find(kind="producer")`, `resolve(hint_kind="producer")`, `_load_node_record` for Producer.
+7. **`java_ontology.py`**: `DECLARES_PRODUCER` in `EDGE_SCHEMA` with `member_only=True`.
+8. **Type-level `describe` rollups**: `DECLARES.DECLARES_PRODUCER`, `OVERRIDDEN_BY.DECLARES_PRODUCER`.
+9. **Async doc sweep** + regenerate `docs/EDGE-NAVIGATION.md` (11 edges).
+10. **Tests** — All **Tests for PR-C** in the plan (verbatim).
 
 ## Out of scope (do NOT touch)
 

plans/PLAN-HINTS-V3.md

@@ -130,7 +130,7 @@ Name tests `test_hints_hv{N}_*` matching propose §6 / §4 rows:
 19. `test_hints_hv19_edge_schema_coverage_exists_trigger_per_edge`
 20. `test_hints_hv20_no_dotkey_edge_labels_in_rendered_neighbors_hints`
 21. `test_hints_neighbors_empty_kind_check_template_removed` — grep/template absent
-22. `test_hints_neighbors_v2_empty_post_flip_method_http_calls` — integration (optional if graph fixture available)
+22. `test_hints_neighbors_v2_empty_post_flip_method_http_calls` — integration round-trip on post-flip graph (**required** once SCHEMA PR-C is on `master`; fail loud if session fixture lacks Client→Route shape)
 
 **Regression:** `test_hints_neighbors_fuzzy_strategy_*` and v1 neighbors tests still pass; update `test_hints_neighbors_empty_with_edge_types_emits_kind_check` → expect new template family (rename to reflect v3 behavior).
 

plans/PLAN-SCHEMA-V2.md

@@ -45,8 +45,8 @@ Depends on:
 | Topic | Decision |
 | --- | --- |
 | `EDGE_SCHEMA` size in v2 | **11** entries after PR-C (`DECLARES_PRODUCER` added); PR-A ships **10** (no Producer table yet). |
-| `typical_traversals` | Role-keyed `dict[str, str]` (`type_subject`, `member_subject`, `alien_subject`, …) finalized in PR-A; hints v3 consumes in PR-D. |
-| `member_only` on `EdgeSpec` | Prefer PR-A; if omitted, PR-D adds (hint-only field; not in DDL CI). |
+| `typical_traversals` | **PR-A contract:** role-keyed `dict[str, str]` per HINTS-V3 §3.5 (`type_subject`, `member_subject`, `alien_subject`, …). SCHEMA-V2 propose Appendix A `tuple[str, …]` examples are **illustrative only** — implementation and hints v3 use the dict shape. |
+| `member_only` on `EdgeSpec` | Hint-only (not in DDL CI). **PR-A:** `True` on `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`, `CALLS` only (10-edge schema). **PR-C:** add `DECLARES_PRODUCER` to `EDGE_SCHEMA` and set `member_only=True` when that edge lands. If PR-A omits the field entirely, PR-D may add it. |
 | `brownfield_resolver_sourced` | Renamed from `brownfield_sourced`; True iff edge carries resolver `strategy` ∈ `BROWNFIELD_RESOLVER_STRATEGY_SET`. |
 | `BROWNFIELD_RESOLVER_STRATEGY_SET` | `FUZZY_STRATEGY_SET` ∪ non-fuzzy resolver strategies used on edges today (`codebase_route`, `codebase_client`, `codebase_producer`, `layer_*`, pass5/6 HTTP/async strategy literals — lock members in PR-A from `grep` of `strategy=` / ontology sets). |
 | `HttpCallRow` / `AsyncCallRow` | PR-B: `client_id` replaces `symbol_id` on HTTP rows. PR-C: `producer_id` replaces `symbol_id` on async rows. |
@@ -70,8 +70,8 @@ Depends on:
   - `ASYNC_CALLS`: `Symbol → Route` (pre-flip)
   - No `DECLARES_PRODUCER` entry yet (PR-C).
 - Add `brownfield_resolver_sourced: bool` on `EdgeSpec`.
-- Add `member_only: bool = False` on `EdgeSpec` (default False); set True on `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`, `CALLS` per HINTS-V3 §3.4 (PR-D depends on this).
-- Add `typical_traversals: dict[str, str]` per edge (role keys; post-flip traversals for HTTP/ASYNC may describe **target** shape — update strings again in PR-B/C when endpoints flip).
+- Add `member_only: bool = False` on `EdgeSpec` (default False). **PR-A only:** set `True` on `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`, `CALLS` (not `DECLARES_PRODUCER` — that edge does not exist until PR-C).
+- Add `typical_traversals: dict[str, str]` per edge (role keys per HINTS-V3 §3.5 — **not** the tuple shape in SCHEMA propose Appendix A). Post-flip traversals for HTTP/ASYNC may describe target shape; update strings again in PR-B/C when endpoints flip.
 - Add `BROWNFIELD_RESOLVER_STRATEGY_SET: frozenset[str]` (Decision 28).
 - Export new symbols in `__all__`.
 
@@ -136,7 +136,7 @@ Depends on:
 4. `test_edge_navigation_doc_matches_generator_output`
 5. `test_edge_navigation_doc_check_mode_detects_drift`
 6. `test_kuzu_graph_refuses_ontology_version_below_required`
-7. `test_edge_schema_member_only_flags_on_method_level_edges` — `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`, `CALLS` True; `HTTP_CALLS`/`ASYNC_CALLS` False at pre-flip.
+7. `test_edge_schema_member_only_flags_on_method_level_edges` — `DECLARES_CLIENT`, `EXPOSES`, `OVERRIDES`, `CALLS` True; no `DECLARES_PRODUCER` key in PR-A schema; `HTTP_CALLS`/`ASYNC_CALLS` False at pre-flip.
 
 ## Definition of done (PR-A)
 
@@ -184,7 +184,7 @@ Depends on:
 - `find_route_callers`: two-hop Cypher
   `MATCH (s:Symbol)-[:DECLARES_CLIENT]->(c:Client)-[e:HTTP_CALLS]->(r:Route …)`.
 - `trace_request_flow` inbound: two-hop via Client; output rows include `caller_node_id`, `caller_node_kind`, `declaring_symbol_id`, `declaring_symbol_fqn`.
-- Impact-analysis expansion (~line 1335): three-hop through Client; surface caller node id on impacted route rows.
+- Impact-analysis expansion in `KuzuGraph` cross-service flow stage (Cypher using `HTTP_CALLS|ASYNC_CALLS` on changed symbols): three-hop through Client; surface caller node id on impacted route rows. Locate via `grep HTTP_CALLS|ASYNC_CALLS` in `kuzu_queries.py` — do not rely on line numbers.
 - Remove all `Symbol-[HTTP_CALLS]->Route` patterns.
 
 ### 4. `pr_analysis.py`
@@ -257,6 +257,7 @@ with every hit accounted for (fixed or justified).
 
 - Add `Producer` to `NodeKind`.
 - Add `EDGE_SCHEMA["DECLARES_PRODUCER"]`, update `ASYNC_CALLS` to `Producer → Route`.
+- Set `member_only=True` on `DECLARES_PRODUCER` (edge lands in this PR).
 - `typical_traversals` for async edges/post-flip producer traversals.
 
 ### 2. `build_ast_graph.py`
@@ -275,27 +276,31 @@ with every hit accounted for (fixed or justified).
 - `find_route_callers` / `trace_request_flow` / impact analysis: include `DECLARES_PRODUCER` + `ASYNC_CALLS` two-hop branch; `caller_node_kind="producer"` with `topic`/`broker` from node.
 - `find` producers query helper (parallel `find_clients`).
 
-### 4. `mcp_v2.py`
+### 4. `pr_analysis.py`
+
+- Extend route reachability for changed symbols: async leg uses `DECLARES_PRODUCER` + `ASYNC_CALLS` two-hop (HTTP leg already two-hop from PR-B).
+
+### 5. `mcp_v2.py`
 
 - Extend `Literal` unions: `"producer"` on `find`, `resolve`, `_node_kind_from_id`, filters.
 - `find_v2(kind="producer")`, `resolve(..., hint_kind="producer")` using `VALID_PRODUCER_KINDS`.
 - `_load_node_record` for Producer.
 
-### 5. `server.py`
+### 6. `server.py`
 
 - `GraphMetaOutput`: optional `producers_total` / `declares_producer_total` if exposed in meta tool (match `build_ast_graph` counters).
 
-### 6. `kuzu_queries.py` — `describe` rollups (~625, ~681)
+### 7. `kuzu_queries.py` — `describe` rollups (type-level `edge_summary` path)
 
 - Add `("DECLARES.DECLARES_PRODUCER", "DECLARES_PRODUCER")` to type rollup set.
 - Add `OVERRIDDEN_BY.DECLARES_PRODUCER` parallel to client axis.
 
-### 7. Docs (async sweep)
+### 8. Docs (async sweep)
 
 - `README.md`, `docs/AGENT-GUIDE.md`, exploration skill — ASYNC_CALLS / Producer navigation.
 - Regenerate `docs/EDGE-NAVIGATION.md` (11 edges).
 
-### 8. Tests / fixtures
+### 9. Tests / fixtures
 
 - `tests/test_call_edges_e2e.py`, `tests/test_brownfield_clients.py` (producer stubs), `tests/test_mcp_v2.py`, `tests/test_ast_graph_build.py`, `tests/test_client_node_extraction.py` (meta counters pattern).
 

propose/HINTS-V3-PROPOSE.md

@@ -1,6 +1,6 @@
 # HINTS-V3 — kind- and direction-aware empty-result hints driven by EDGE_SCHEMA
 
-**Status**: draft
+**Status**: merged
 **Author**: Dmitriy Teriaev
 **Date**: 2026-05-16