Skip to content

Commit afcbf82

Browse files
HumanBean17cursoragent
HumanBean17
and
cursoragent
authored
plan: hints v4 success-path road signs (#174)
* lock hints v4 propose and add implementation plan Co-authored-by: Cursor <cursoragent@cursor.com> * fix hints v4 plan: flat subject_record gate and review follow-ups Align N1a/N1b type-subject detection with v3 (Kuzu row top-level kind, not NodeRecord.data). Require neighbors_v2 round-trip test; sync propose test table (N6, F3); document multi-origin and method+constructor homogeneity. Co-authored-by: Cursor <cursoragent@cursor.com> --------- Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent 528838d commit afcbf82

3 files changed

Lines changed: 438 additions & 5 deletions

File tree

‎plans/CURSOR-PROMPTS-HINTS-V4.md‎

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
# Cursor task prompts — HINTS-V4
2+
3+
Status: **active**. Plan:
4+
[`plans/PLAN-HINTS-V4.md`](./PLAN-HINTS-V4.md). Propose:
5+
[`propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md`](../propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md).
6+
7+
**Depends on:** NEIGHBORS-DOT-KEY ([#171](https://github.com/HumanBean17/java-codebase-rag/pull/171)) on `master`.
8+
9+
**Propose lock:** Locked in planning PR [#174](https://github.com/HumanBean17/java-codebase-rag/pull/174); must remain locked before PR-A **merge**.
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-HINTS-V4-A — `neighbors` success-path catalog (N1a–N7)
21+
22+
**Branch:** `feat/hints-v4-neighbors-success` off `master`.
23+
**Base:** `master` (with #171 merged).
24+
**Plan section:** [`plans/PLAN-HINTS-V4.md`](./PLAN-HINTS-V4.md) § PR-A.
25+
**PR title:** `feat(hints): v4 success-path neighbors road signs (N1a–N7)`
26+
27+
**Attach (`@-files`):**
28+
29+
- `@plans/PLAN-HINTS-V4.md`
30+
- `@propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md`
31+
- `@propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md` (priority cap §7.12)
32+
- `@propose/completed/HINTS-V2-PROPOSE.md` (no per-row neighbors hints)
33+
- `@propose/completed/HINTS-V3-PROPOSE.md` (empty neighbors; dot-key prohibition)
34+
- `@propose/completed/NEIGHBORS-DOT-KEY-TRAVERSAL-PROPOSE.md` (dot-key context)
35+
- `@mcp_hints.py`
36+
- `@mcp_v2.py` (`neighbors_v2` payload — read only unless field missing)
37+
- `@tests/test_mcp_hints.py`
38+
39+
**Prompt:**
40+
41+
````
42+
You are implementing PR-HINTS-V4-A from `plans/PLAN-HINTS-V4.md`.
43+
44+
Confirm `propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md` is **Status: locked** before merge.
45+
46+
## Scope
47+
48+
1. **`mcp_hints.py`**
49+
- Add v4 neighbors success templates N2–N7 (verbatim strings in plan).
50+
- N1a/N1b: reuse `TPL_DESCRIBE_TYPE_CLIENTS_VIA_MEMBERS` and `TPL_DESCRIBE_TYPE_ROUTES_VIA_MEMBERS` — do not fork wording.
51+
- Implement `neighbors_success_hints(payload)` per propose trigger contract (single edge type, offset 0, homogeneous `other`, char cap 120).
52+
- **N1a/N1b type gate:** flat Kuzu `subject_record` from `neighbors_v2` — `_subject_node_label == "Symbol"` and top-level `subject_record["kind"] in _TYPE_SYMBOL_KINDS` (same as v3 `neighbors_empty_hints`; **not** nested `data.kind` / `NodeRecord.model_dump()`).
53+
- **Homogeneity:** method + constructor on one page = OK (both ∈ `_METHOD_SYMBOL_KINDS`); method + type Symbol = silent.
54+
- Wire `generate_hints("neighbors", …)`: call success helper on non-empty `results`; keep empty + fuzzy paths unchanged.
55+
- **Critical:** `_filter_neighbors_dotkey_hints` applies to **empty structural pairs only** — success-path N1a/N1b must retain `DECLARES.*` dot-keys.
56+
- Module docstring: reference HINTS-V4 propose.
57+
58+
2. **`tests/test_mcp_hints.py`**
59+
- Implement every test name under **Tests for PR-A** in `plans/PLAN-HINTS-V4.md` (including N6 and **required** `test_hints_neighbors_v2_declares_success_emits_dot_key_clients`).
60+
- Synthetic `subject_record`: flat `{"id": "sym:…", "kind": "class"}` — **not** `NodeRecord.model_dump()`.
61+
- Narrow `test_hints_hv20_no_dotkey_edge_labels_in_rendered_neighbors_hints` to **empty** payloads only.
62+
- Add `test_hints_neighbors_success_may_emit_declares_dot_keys` (synthetic flat subject).
63+
- Add `test_hints_all_v4_templates_under_120_chars` (parametrize templates + realistic ids).
64+
65+
## Out of scope (do NOT touch)
66+
67+
- `mcp_v2.py` (unless payload field genuinely missing — unexpected).
68+
- `build_ast_graph.py`, `java_ontology.py`, `ONTOLOGY_VERSION`, `EDGE_SCHEMA`.
69+
- `find` / `search` success hints (PR-B).
70+
- `describe` / `resolve` catalog rows.
71+
- `MCP_HINTS_FIELD_DESCRIPTION`, `README.md`, `server.py`.
72+
- `propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md` (PR-B appendix).
73+
- Per-row hints; ontology bump.
74+
75+
## Deliverables
76+
77+
1. N1a–N7 success-path hints on matching non-empty `neighbors` payloads.
78+
2. Dot-key filter split: empty structural never has dot-keys; success N1a/N1b may.
79+
3. All PR-A named tests pass.
80+
81+
## Tests to run
82+
83+
```bash
84+
.venv/bin/ruff check mcp_hints.py tests/test_mcp_hints.py
85+
.venv/bin/python -m pytest tests/test_mcp_hints.py -v -k "hints_neighbors or hints_all_v4 or hv20 or v2_declares_success"
86+
```
87+
88+
Before PR open:
89+
90+
```bash
91+
.venv/bin/ruff check .
92+
.venv/bin/python -m pytest tests -v
93+
```
94+
95+
## Sentinel checks (`git diff master..HEAD` — zero matches)
96+
97+
- `ONTOLOGY_VERSION`
98+
- `build_ast_graph.py` (unless accidental touch — revert)
99+
- `TPL_FIND_SUCCESS` / `find_success_hints` (PR-B)
100+
- `TPL_SEARCH_SUCCESS` (PR-B unless mistakenly added in A)
101+
102+
## Definition of done
103+
104+
- [ ] PR-A checklist in `plans/PLAN-HINTS-V4.md` satisfied.
105+
- [ ] Propose still **locked**; `test_hints_neighbors_v2_declares_success_emits_dot_key_clients` passes.
106+
- [ ] PR body: scope, plan + propose links, note lossy N1a/N1b, **no re-index**.
107+
````
108+
109+
---
110+
111+
## PR-HINTS-V4-B — `find` success-path (+ optional S1, appendix)
112+
113+
**Branch:** `feat/hints-v4-find-success` off `master` (or rebase on PR-A merge).
114+
**Base:** `master` after PR-A merged (or include PR-A commits if stacked).
115+
**Plan section:** [`plans/PLAN-HINTS-V4.md`](./PLAN-HINTS-V4.md) § PR-B.
116+
**PR title:** `feat(hints): v4 success-path find road signs (F1–F3)`
117+
118+
**Attach (`@-files`):**
119+
120+
- `@plans/PLAN-HINTS-V4.md`
121+
- `@propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md`
122+
- `@mcp_hints.py`
123+
- `@tests/test_mcp_hints.py`
124+
- `@propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md` (appendix only)
125+
126+
**Prompt:**
127+
128+
````
129+
You are implementing PR-HINTS-V4-B from `plans/PLAN-HINTS-V4.md`.
130+
131+
PR-A (neighbors N1a–N7) is on `master`.
132+
133+
## Scope
134+
135+
1. **`mcp_hints.py`**
136+
- Add F1–F3 templates and `find_success_hints(payload)`.
137+
- Wire `generate_hints("find", …)` — success hints at `PRIORITY_LEAF_FOLLOWUP`; page-full stays `PRIORITY_META`.
138+
- Page-full gate: do not emit F-rows when `len(results) >= limit` and `has_more_results is True`.
139+
- `{id}` = `results[0]["id"]` when multiple matches (document in PR — not per-row).
140+
- **Optional:** S1 `search` single-hit → `describe(id='{symbol_id}')` only if plan reviewer approved; else skip S1 and its test.
141+
142+
2. **`propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md`**
143+
- Add short v4 amendment paragraph (#163): second partial dot-key reversal for type-origin neighbors success path only.
144+
145+
3. **`tests/test_mcp_hints.py`**
146+
- `test_hints_find_route_success_emits_handler`
147+
- `test_hints_find_client_success_emits_http_calls`
148+
- `test_hints_find_producer_success_emits_async_calls`
149+
- `test_hints_search_single_hit_emits_describe` — only if S1 implemented
150+
151+
## Out of scope (do NOT touch)
152+
153+
- Graph builder, ontology, `mcp_v2.py` (find payload already has `kind`, `results`, `limit`, `has_more_results`).
154+
- Neighbors success catalog changes except regressions.
155+
- `MCP_HINTS_FIELD_DESCRIPTION` change.
156+
- `README.md` / `server.py` unless explicitly requested by reviewer.
157+
158+
## Deliverables
159+
160+
1. F1–F3 on non-page-full find success payloads.
161+
2. Appendix paragraph in HINTS-ROAD-SIGNS completed propose.
162+
3. Optional S1 + test if shipped.
163+
164+
## Tests to run
165+
166+
```bash
167+
.venv/bin/ruff check mcp_hints.py tests/test_mcp_hints.py propose/completed/HINTS-ROAD-SIGNS-PROPOSE.md
168+
.venv/bin/python -m pytest tests/test_mcp_hints.py -v -k "hints_find_route_success or hints_find_client or hints_find_producer or hints_search_single"
169+
```
170+
171+
Before PR open:
172+
173+
```bash
174+
.venv/bin/ruff check .
175+
.venv/bin/python -m pytest tests -v
176+
```
177+
178+
## Sentinel checks (`git diff master..HEAD` — zero matches)
179+
180+
- `ONTOLOGY_VERSION`
181+
- `build_ast_graph.py`
182+
- Changes to `neighbors_success_hints` trigger table (PR-A owned)
183+
184+
## Landing hygiene (after PR-B merges)
185+
186+
- Move `propose/HINTS-V4-SUCCESS-PATH-PROPOSE.md` → `propose/completed/`
187+
- Move `plans/PLAN-HINTS-V4.md` and this file → `plans/completed/`
188+
189+
## Definition of done
190+
191+
- [ ] PR-B checklist in plan satisfied.
192+
- [ ] PR body: F1 uses first result id when multiple matches; no re-index.
193+
````

0 commit comments

Comments
 (0)