Skip to content

Commit ec1569b

Browse files
HumanBean17cursoragent
HumanBean17
and
cursoragent
authored
add plan and cursor prompts for OVERRIDDEN_BY.* dot-key traversal (#187)
Execution-ready delivery plan for propose #165 / issue #165; single PR with merge-blocking rollup↔traversal parity tests. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent dc1048a commit ec1569b

2 files changed

Lines changed: 395 additions & 0 deletions

File tree

‎plans/CURSOR-PROMPTS-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
# Cursor task prompts — OVERRIDDEN-BY-DOT-KEY-TRAVERSAL
2+
3+
Status: **active**. Plan:
4+
[`plans/PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md`](./PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md). Propose:
5+
[`propose/OVERRIDDEN-BY-DOT-KEY-TRAVERSAL-PROPOSE.md`](../propose/OVERRIDDEN-BY-DOT-KEY-TRAVERSAL-PROPOSE.md).
6+
7+
**Depends on:** landed `DECLARES.*` dot-key traversal ([#171](https://github.com/HumanBean17/java-codebase-rag/pull/171)); stored `[:OVERRIDES]` edges.
8+
9+
One prompt: **PR-1** (single implementation PR).
10+
11+
**Universal rules:**
12+
13+
- Use `.venv/bin/python` and `.venv/bin/ruff` only.
14+
- No stdout from MCP handlers.
15+
- Do not expand scope beyond the plan.
16+
- Do not push git unless the user asked.
17+
18+
---
19+
20+
## PR-OVERRIDDEN-BY-1 — `OVERRIDDEN_BY.*` dot-key traversal
21+
22+
**Branch:** `feat/overridden-by-dot-key-traversal` off `master`.
23+
**Base:** `master`.
24+
**Plan section:** [`plans/PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md`](./PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md) § PR-1.
25+
**PR title:** `feat(neighbors): navigate OVERRIDDEN_BY.* composed edge types in one call`
26+
27+
**Attach (`@-files`):**
28+
29+
- `@plans/PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md`
30+
- `@propose/OVERRIDDEN-BY-DOT-KEY-TRAVERSAL-PROPOSE.md`
31+
- `@kuzu_queries.py` (`override_axis_rollup_for`, `member_edge_traversal_for` — mirror for override traversal)
32+
- `@mcp_v2.py` (`neighbors_v2`, `ComposedEdgeType`, `NodeRecord.edge_summary`)
33+
- `@mcp_hints.py` (`TPL_DESCRIBE_METHOD_*_IN_OVERRIDERS`, `MCP_HINTS_FIELD_DESCRIPTION`)
34+
- `@server.py` (`neighbors` / `describe` tool descriptions)
35+
- `@docs/AGENT-GUIDE.md`
36+
- `@docs/EDGE-NAVIGATION.md`
37+
- `@README.md` (MCP tool table only)
38+
- `@tests/test_mcp_v2_compose.py`
39+
- `@tests/test_mcp_hints.py`
40+
- `@tests/fixtures/override_axis_rollup_smoke/` (fixture corpus)
41+
42+
**Prompt:**
43+
44+
````
45+
You are implementing PR-OVERRIDDEN-BY-1 from `plans/PLAN-OVERRIDDEN-BY-DOT-KEY-TRAVERSAL.md`.
46+
47+
## Scope
48+
49+
1. **`kuzu_queries.py`** — Add `_OVERRIDE_AXIS_COMPOSED_REL_MAP` and `override_axis_traversal_for` per propose (stored `[:OVERRIDES]` dispatch hop; base key returns overrider method ids without `via_id`; composed keys return terminal rows with full attr projection + `via_id`). Export override composed key allowlist for `mcp_v2`. Do **not** change `override_axis_rollup_for`.
50+
51+
2. **`mcp_v2.py`**
52+
- Extend `ComposedEdgeType` with four `OVERRIDDEN_BY*` literals.
53+
- Partition composed keys into member (`DECLARES.*`) vs override (`OVERRIDDEN_BY.*`) registries.
54+
- Refactor `neighbors_v2`: axis-specific origin gates; **fail-fast** when mixed families cannot both apply to the same origin; `direction="out"` for any composed key.
55+
- Override traversal: `override_axis_traversal_for`; `edge_type` = dot-key; composed `attrs` include `via_id`.
56+
- Update `NodeRecord.edge_summary` description (both composed families navigable with correct origin constraints).
57+
58+
3. **`server.py`** — Update `describe` / `neighbors` tool descriptions for override-axis dot-keys.
59+
60+
4. **`mcp_hints.py`** — Rewrite `TPL_DESCRIBE_METHOD_OVERRIDERS`, `TPL_DESCRIBE_METHOD_CLIENTS_IN_OVERRIDERS`, `TPL_DESCRIBE_METHOD_PRODUCERS_IN_OVERRIDERS`, `TPL_DESCRIBE_METHOD_ROUTES_IN_OVERRIDERS` to single-call `neighbors(..., ['OVERRIDDEN_BY.*'])`. Update `MCP_HINTS_FIELD_DESCRIPTION`. **Do not** remove `_filter_neighbors_dotkey_hints`.
61+
62+
5. **Docs** — `docs/AGENT-GUIDE.md`, `docs/EDGE-NAVIGATION.md`, minimal `README.md` neighbors row; document `OVERRIDDEN_BY` `out` vs stored `OVERRIDES` `in` equivalence.
63+
64+
6. **Tests** — Implement every test name under **Tests for PR-1** in the plan:
65+
- Replace `test_neighbors_still_rejects_overridden_by` with `test_neighbors_accepts_overridden_by_dot_keys`.
66+
- Merge-blocking: `test_neighbors_overridden_by_rollup_traversal_parity_blocking` (all four keys, bank-chat `ChatAssignmentPort.requestAssignment` + `override_axis_rollup_smoke`).
67+
- Update `test_describe_interface_method_with_annotated_impl_emits_rollup` (no `ValidationError` on `OVERRIDDEN_BY`).
68+
- Add `test_hints_describe_method_overridden_by_declares_client_emits_dot_key`; update existing describe-method overrider hint tests.
69+
- Grep regression: no `then neighbors(overrider_ids` in the four `TPL_DESCRIBE_METHOD_*_IN_OVERRIDERS` templates.
70+
71+
## Out of scope (do NOT touch)
72+
73+
- `build_ast_graph.py`, `java_ontology.py` `ONTOLOGY_VERSION` / ontology bump, graph DDL, enrichment passes
74+
- `override_axis_rollup_for` counting logic changes
75+
- Inbound composed `direction="in"` for override-axis keys
76+
- Per-method `NodeRef` signals ([#167](https://github.com/HumanBean17/java-codebase-rag/issues/167))
77+
- `search` / `find` result shape changes
78+
- Moving propose to `completed/` (reviewer may do on merge)
79+
- Edits under `tests/bank-chat-system/` fixture sources
80+
81+
## Deliverables
82+
83+
1. `neighbors(['<interface_method_id>'], 'out', ['OVERRIDDEN_BY.DECLARES_CLIENT'])` returns Client `NodeRef`s with `via_id` = overrider method id.
84+
2. **Parity:** unfiltered `len(results)` == `describe(...).record.edge_summary[key]["out"]` for each override-axis key (merge-blocking).
85+
3. `DECLARES.*` behavior unchanged; mixed-family wrong-origin returns `success=False` for the whole request.
86+
4. Docs + hints aligned with “what you see in edge_summary is what you can request” for `OVERRIDDEN_BY*`.
87+
88+
## Tests to run
89+
90+
```bash
91+
.venv/bin/ruff check kuzu_queries.py mcp_v2.py mcp_hints.py server.py tests/test_mcp_v2_compose.py tests/test_mcp_hints.py
92+
.venv/bin/python -m pytest tests/test_mcp_v2_compose.py tests/test_mcp_hints.py -v -k "overridden_by or override_axis or hints_describe_method or parity_blocking or mixed_composed"
93+
```
94+
95+
Before PR open:
96+
97+
```bash
98+
.venv/bin/ruff check .
99+
.venv/bin/python -m pytest tests -v
100+
```
101+
102+
## Sentinel checks (`git diff master..HEAD` — zero matches)
103+
104+
- `ONTOLOGY_VERSION` assignment changes in `java_ontology.py`
105+
- `ontology_version` bump in `build_ast_graph.py`
106+
- New graph pass files or `pass7` references
107+
- `then neighbors(overrider_ids` in `mcp_hints.py` `TPL_DESCRIBE_METHOD_*_IN_OVERRIDERS` templates
108+
- Edits under `tests/bank-chat-system/` fixture sources
109+
110+
## Definition of done
111+
112+
- All plan PR-1 checklist items checked.
113+
- Parity tests green **before** merge (not deferred).
114+
- PR description: scope, link to propose #165, manual evidence (one `describe` + `neighbors` dot-key on `ChatAssignmentPort.requestAssignment`), note stored-`OVERRIDES` dispatch hop (not signature Cypher in read path).
115+
116+
## Manual evidence (paste in PR)
117+
118+
```bash
119+
KUZU=/tmp/ob-dotkey-evidence/code_graph.kuzu
120+
rm -rf /tmp/ob-dotkey-evidence
121+
.venv/bin/python build_ast_graph.py \
122+
--source-root tests/bank-chat-system \
123+
--kuzu-path "$KUZU" --verbose
124+
# Resolve ChatAssignmentPort.requestAssignment method id (Cypher or test helper), then:
125+
# describe(mid) → note OVERRIDDEN_BY.DECLARES_CLIENT out count
126+
# neighbors_v2(mid, direction='out', edge_types=['OVERRIDDEN_BY.DECLARES_CLIENT']) → len(results) matches
127+
```
128+
129+
Compare counts to `describe.edge_summary` for all four override-axis keys on that method.
130+
131+
````

0 commit comments

Comments
 (0)