diff --git a/docs/AGENT-GUIDE.md b/docs/AGENT-GUIDE.md index 7fb41c7..5174bc8 100644 --- a/docs/AGENT-GUIDE.md +++ b/docs/AGENT-GUIDE.md @@ -234,7 +234,7 @@ Returns **edges** with `attrs` (`confidence`, `strategy`, `match`, … on cross- **Cross-service edges** (`HTTP_CALLS`, `ASYNC_CALLS`): read `attrs.confidence` and `attrs.match` — low confidence or `unresolved`/`phantom`/`ambiguous` means treat as a resolver signal, not ground truth. -**`CALLS` edges:** source-ordered (`call_site_line`, `call_site_byte`). After ontology 15 PR-3, true receiver-failure sites are **not** on `CALLS` — they are `UnresolvedCallSite` nodes (`reason`: `chained_receiver` or `phantom_unresolved_receiver`; ids use the `ucs:` prefix, `other.kind=unresolved_call_site` — **not** describable via `describe(id=…)`). `UNRESOLVED_AT` is graph storage only (not in `EDGE_SCHEMA` / `neighbors` edge_types). `attrs.resolved=false` on remaining `CALLS` rows means known-receiver-external (JDK/Spring) callees, not receiver failure. **`include_unresolved=True`** (CALLS + `direction=out` only) interleaves unresolved sites with resolved `CALLS` (`row_kind` discriminator); **mutually exclusive with `edge_filter`**. **`dedup_calls=True`** collapses identical `(origin, callee)` `CALLS` to one row with `call_site_lines`. **`filter` + `edge_filter` together** load the ordered CALLS stream then apply callee `NodeFilter` in Python — expect higher latency on hot methods than `edge_filter` alone. Optional **`edge_filter`** projects before pagination: `min_confidence`; `include_strategies` / `exclude_strategies` (mutually exclusive); `callee_declaring_role`, `callee_declaring_roles`, `exclude_callee_declaring_roles` (`["OTHER"]` also drops known-external rows). **`filter.role` filters the neighbor method (usually `OTHER`), not the callee stereotype** — use `edge_filter.callee_declaring_role` for repository/service hops. **`exclude_external` applies to `find_callers` / `find_callees` only** (FQN-prefix); trim JDK noise on `neighbors` CALLS via `edge_filter`. Accessor noise: role excludes help; getter/setter heuristics in [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map`. +**`CALLS` edges:** source-ordered (`call_site_line`, `call_site_byte`). After ontology 15 PR-3, true receiver-failure sites are **not** on `CALLS` — they are `UnresolvedCallSite` nodes (`reason`: `chained_receiver` or `phantom_unresolved_receiver`; ids use the `ucs:` prefix, `other.kind=unresolved_call_site` — **not** describable via `describe(id=…)`). `UNRESOLVED_AT` is graph storage only (not in `EDGE_SCHEMA` / `neighbors` edge_types). `attrs.resolved=false` on remaining `CALLS` rows means known-receiver-external (JDK/Spring) callees, not receiver failure. **`include_unresolved=True`** (CALLS + `direction=out` only) interleaves unresolved sites with resolved `CALLS` (`row_kind` discriminator); **mutually exclusive with `edge_filter`**. **`dedup_calls=True`** collapses identical `(origin, callee)` `CALLS` to one row with `call_site_lines`. **`filter` + `edge_filter` together** load the ordered CALLS stream then apply callee `NodeFilter` in Python — expect higher latency on hot methods than `edge_filter` alone. Optional **`edge_filter`** projects before pagination: `min_confidence`; `include_strategies` / `exclude_strategies` (mutually exclusive); `callee_declaring_role`, `callee_declaring_roles`, `exclude_callee_declaring_roles` (`["OTHER"]` also drops known-external rows). **`filter.role` filters the neighbor method (usually `OTHER`), not the callee stereotype** — use `edge_filter.callee_declaring_role` for repository/service hops. **`exclude_external` applies to `find_callers` / `find_callees` only** (FQN-prefix); trim JDK noise on `neighbors` CALLS via `edge_filter`. Accessor noise: role excludes help; getter/setter heuristics in [`propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map`. ### Ontology glossary diff --git a/docs/paper/README.md b/docs/paper/README.md index c9802a8..7ad063d 100644 --- a/docs/paper/README.md +++ b/docs/paper/README.md @@ -71,7 +71,7 @@ that is acceptable. - **First draft**: 2026-05-08, opened as PR (`docs/architecture-paper`). - **Empirical evaluation**: deferred to a follow-up paper or a §7.1 addition once real-codebase testing produces stable numbers. -- **Skills layer specification**: deferred to `propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md` +- **Skills layer specification**: deferred to `propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md` (currently held in PR #59); empirical signals from current testing show prose-guide-only is sufficient, so the skills layer is not on the critical path. diff --git a/plans/completed/PLAN-CALLS-NOISE.md b/plans/completed/PLAN-CALLS-NOISE.md index 66e738d..4bfaf04 100644 --- a/plans/completed/PLAN-CALLS-NOISE.md +++ b/plans/completed/PLAN-CALLS-NOISE.md @@ -6,7 +6,7 @@ Source propose: (tracks [#177](https://github.com/HumanBean17/java-codebase-rag/issues/177)). Depends on: **SCHEMA-V2 landed** (`EDGE_SCHEMA`, MCP v2 tools). Complements -[`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) +[`propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` for accessor noise (Decision 39) — not a blocker. **Cursor prompts:** [`plans/completed/AGENT-PROMPTS-CALLS-NOISE.md`](./AGENT-PROMPTS-CALLS-NOISE.md) diff --git a/plans/active/PLAN-HINTS-STRING-REMOVAL.md b/plans/completed/PLAN-HINTS-STRING-REMOVAL.md similarity index 99% rename from plans/active/PLAN-HINTS-STRING-REMOVAL.md rename to plans/completed/PLAN-HINTS-STRING-REMOVAL.md index 7f47f58..69a88ef 100644 --- a/plans/active/PLAN-HINTS-STRING-REMOVAL.md +++ b/plans/completed/PLAN-HINTS-STRING-REMOVAL.md @@ -1,7 +1,7 @@ # Plan: HINTS-STRING-REMOVAL -Status: **active**. This plan implements -[`propose/active/HINTS-STRING-REMOVAL-PROPOSE.md`](../../propose/active/HINTS-STRING-REMOVAL-PROPOSE.md) +Status: **completed**. This plan implements +[`propose/completed/HINTS-STRING-REMOVAL-PROPOSE.md`](../propose/completed/HINTS-STRING-REMOVAL-PROPOSE.md) as a single PR. Depends on: none (all prerequisite work — `hints_structured` with `label` — is landed). diff --git a/propose/active/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md b/propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md similarity index 100% rename from propose/active/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md rename to propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md diff --git a/propose/completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md b/propose/completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md index 23e3444..93892e5 100644 --- a/propose/completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md +++ b/propose/completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md @@ -19,7 +19,7 @@ - Out: `min_confidence` and `exclude_strategies` as `neighbors_v2` parameters (subsumed by `edge_filter`); a `CALLS` semantic split into `DELEGATES_TO` / `PERSISTS_VIA` / `ACCESSES_STATE`; `callee_capability` / `callee_annotation` / `callee_microservice` filter axes; `EdgeFilter` on `find_callers`; an MCP surface for "find unresolved callers"; package-relativity filters; multi-hop `neighbors_v2`; per-edge dedup as a `neighbors_v2` knob (kept as a CALLS-specific response shape decision in PR-3). - **MCP ordering contract (PR-2):** `neighbors_v2` today does not `ORDER BY` CALLS rows; PR-2 locks `ORDER BY e.call_site_line, e.call_site_byte` for every CALLS path (flat, `edge_filter`, and PR-3 `include_unresolved` interleave). - **`exclude_external` is not added to `neighbors_v2`.** It remains on `find_callers` / `find_callees` only (Decision 38). JDK/library noise on default `neighbors(out, ['CALLS'])` is addressed via `edge_filter` (`min_confidence`, `exclude_strategies`) after PR-2, not FQN-prefix rules. -- **Accessor noise is only partly solved** by `callee_declaring_role`; entity getter/setter discrimination needs heuristics — see cross-link to [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` (Decision 39). +- **Accessor noise is only partly solved** by `callee_declaring_role`; entity getter/setter discrimination needs heuristics — see cross-link to [`propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` (Decision 39). - Non-obvious constraint: `pass3_calls` and `find_callers` currently rely on phantom Symbol rows existing as the `dst` endpoint of `strategy='phantom'`/`'chained_receiver'` CALLS rows. PR-3 changes that invariant atomically. Known-receiver-external phantom-FQN rows (line 1257-1271) are kept; only true receiver-failure phantoms are removed. ### Fixture anchors (pinned for tests and HV rows) @@ -446,7 +446,7 @@ These rows capture the workflows that *triggered* #177 — the things an agent w | Moving known-receiver-external rows (`build_ast_graph.py:1257-1271`) out of `CALLS` | Reviewer-flagged data-loss bug in revision 2. These rows carry preserved receiver-tier `strategy`/`confidence`/`arg_count` and a deterministic phantom FQN — real signal, not noise. README §"Phantom nodes" documents the existing contract. Decision 34 records this. | | Silent-no-op `edge_filter` on edges that don't carry the attribute | Contradicts `mcp_v2.py:6,82-91,191-206` fail-loud-on-inapplicable-fields contract. Reverted in revision 3 — Principle 7 + Decision 10 now fail-loud (HV13). | | `exclude_external` on `neighbors_v2` | Duplicates `find_callers` FQN-prefix logic on a different surface; use `edge_filter` on `neighbors` instead (Decision 38). Document asymmetry in AGENT-GUIDE. | -| Method-level accessor labels (`ACCESSOR` vs business logic on same `ENTITY` type) | `callee_declaring_role` alone cannot split getters from real entity methods. Use [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` heuristics or a future propose (Decision 39). | +| Method-level accessor labels (`ACCESSOR` vs business logic on same `ENTITY` type) | `callee_declaring_role` alone cannot split getters from real entity methods. Use [`propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` heuristics or a future propose (Decision 39). | | Porting `/mini-map` classification into the indexer | Skill-side remedy is intentional; server-side role projection closes phantom/chained + stereotype buckets only. | ## §6 — Migration plan — 3 PRs @@ -554,7 +554,7 @@ This propose locks before any code PR merges. The propose itself merges as a sep 36. **`neighbors_v2` CALLS paths use `ORDER BY e.call_site_line, e.call_site_byte` before `offset`/`limit`.** PR-2. Applies to empty-filter, `edge_filter`, and (PR-3) `include_unresolved` interleave. 37. **`edge_filter` predicates are pushed into Cypher `WHERE` for `edge_types=['CALLS']`**, then `NodeFilter` on terminal nodes, then slice. No pre-filter SQL `LIMIT`. PR-2. 38. **`exclude_external` is not added to `neighbors_v2`.** Document asymmetry with `find_callers` / `find_callees` in AGENT-GUIDE. PR-2. -39. **Accessor / getter noise is out of scope for the indexer** — partially addressed by `exclude_callee_declaring_roles`; full remedy is client-side via [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` until a future method-level label propose. +39. **Accessor / getter noise is out of scope for the indexer** — partially addressed by `exclude_callee_declaring_roles`; full remedy is client-side via [`propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` until a future method-level label propose. ## §8 — Risks and how we mitigate @@ -677,5 +677,5 @@ ALTER NODE TABLE GraphMeta ADD COLUMN pass3_unresolved_chained INT64; - Builds on `propose/completed/SCHEMA-V2-PROPOSE.md` §3.4 (`EDGE_SCHEMA`) — extends with `callee_declaring_role` registration. - Builds on `propose/completed/HINTS-V3-PROPOSE.md` (kind/direction templates) — existing templates unchanged; PR-3 adds §3.10 templates per §3.9.1. - Builds on `propose/completed/HINTS-V4-SUCCESS-PATH-PROPOSE.md` — high-fanout and unresolved-presence templates plug into the existing success-path generator. -- Complements [`propose/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` for accessor/getter noise (Decision 39) — server-side `edge_filter` does not replace skill heuristics. +- Complements [`propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](../propose/completed/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) `/mini-map` for accessor/getter noise (Decision 39) — server-side `edge_filter` does not replace skill heuristics. - Resolves [#177](https://github.com/HumanBean17/java-codebase-rag/issues/177). diff --git a/propose/active/HINTS-STRING-REMOVAL-PROPOSE.md b/propose/completed/HINTS-STRING-REMOVAL-PROPOSE.md similarity index 100% rename from propose/active/HINTS-STRING-REMOVAL-PROPOSE.md rename to propose/completed/HINTS-STRING-REMOVAL-PROPOSE.md