docs: complete HTTP brownfield PR-3 (agent guide, addendum, plan)

docs/AGENT-GUIDE.md

@@ -12,9 +12,13 @@
 > `neighbors` arguments, pass stringified JSON, or use vector search for
 > questions the graph answers exactly. This guide keeps them on the rails.
 >
-> Calibrated against ontology version **11** (see `ast_java.ONTOLOGY_VERSION` /
-> `java_ontology.py` valid sets). Design rationale:
-> [`propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md`](../propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md).
+> Calibrated against ontology version **12** (see `ast_java.ONTOLOGY_VERSION` /
+> `java_ontology.py` valid sets): HTTP brownfield rename (`@CodebaseHttpClient`),
+> shared `CodebaseHttpMethod` enum, inbound layer-C HTTP routes replace same-method
+> built-in rows. **Design rationale:** navigation surface and tools —
+> [`propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md`](../propose/completed/MCP-API-V2-REDESIGN-PROPOSE.md);
+> HTTP brownfield rename, `CodebaseHttpMethod`, and exclusivity —
+> [`propose/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md`](../propose/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md).
 
 ---
 
@@ -51,6 +55,14 @@ Treat the following as out of frame:
 When MCP disagrees with the open file, the file wins; report the
 disagreement as evidence of staleness, not as a contradiction.
 
+### Brownfield HTTP annotations (exclusivity)
+
+When a method carries **`@CodebaseHttpRoute`** or **`@CodebaseHttpClient`** (including plural containers), the extractor treats that annotation as the **only** source of truth for the facets it declares (`path`, HTTP verb, `targetService`, `clientKind`, etc.). Framework annotations on the **same** method that would normally drive route or client inference—Spring MVC/WebFlux mapping annotations, **`@FeignClient`**-scoped method mappings, JAX-RS verb annotations, and the like—are **bypassed** for that axis. Do not assume the graph “merges” brownfield with the framework row; for inbound HTTP, layer-C brownfield routes **replace** same-method built-in Spring rows in the graph.
+
+**Observability:** If brownfield and shadowable framework annotations **co-exist** on a method, a **verbose** graph build emits a structured stderr line with **`event=brownfield-exclusivity-shadowing`** (severity INFO), listing which framework annotation simple names were skipped. Typical operator invocation: `.venv/bin/python build_ast_graph.py --source-root … --kuzu-path … --verbose`. Non-verbose builds may omit this traffic.
+
+**UC10 (silent disagreement):** The brownfield annotation wins even when its HTTP verb or path disagrees with what Spring or Feign shows on the method (for example Feign **`@GetMapping`** vs brownfield **`CodebaseHttpMethod.POST`**). There is **no** merge-time warning for that mismatch—wrong assumptions surface at runtime (for example HTTP 405) or through code review. When auditing, prefer the indexed brownfield row and, if needed, the verbose shadowing log over the framework-only reading.
+
 **Workflow (GPS model):**
 
 1. **Locate** — `search` (natural language / fragment) or `find` (structured `NodeFilter`).
@@ -193,7 +205,7 @@ Exact allowed values for roles, capabilities, client kinds, etc. live in `java_o
 - **Batching:** Multiple origins are expanded; pagination slices the **combined** edge list — use larger `limit` when batching many ids.
 - **Confidence:** Cross-service edges (`HTTP_CALLS`, `ASYNC_CALLS`) carry confidence, strategy, and match metadata on `edge.attrs` (`attrs.confidence`, `attrs.strategy`, `attrs.match`). Low confidence means the resolver had to guess at the route binding — treat it as a **resolver gap signal**, not a hallucination. Report low-confidence edges with their confidence value, not as facts. Intra-service edges (`CALLS`, `INJECTS`, `IMPLEMENTS`, `EXTENDS`, `DECLARES`, `DECLARES_CLIENT`, `EXPOSES`) faithfully represent the static graph; the resolved set is still a **lower bound** under reflection / dynamic dispatch (see *What this MCP is NOT*).
 
-### Ontology glossary (version 11)
+### Ontology glossary (version 12)
 
 Source of truth: `java_ontology.py`. Strings are case-sensitive.
 

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

@@ -1,7 +1,9 @@
 # Plan: HTTP brownfield enum method, `@CodebaseHttpClient` rename, inbound exclusivity
 
-Status: **active (planning)**. This plan implements
+Status: **complete**. This plan implements
 [`propose/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md`](../propose/HTTP-ROUTE-METHOD-ENUM-PROPOSE.md).
+PR-1 and PR-2 landed earlier on `master`; PR-3 adds agent docs and the v2 addendum
+[`propose/completed/BROWNFIELD-ANNOTATIONS-V2-ADDENDUM-HTTP-METHOD-ENUM.md`](../propose/completed/BROWNFIELD-ANNOTATIONS-V2-ADDENDUM-HTTP-METHOD-ENUM.md).
 
 Depends on: **none** (lands on current `master`).
 
@@ -210,9 +212,9 @@ Landing order: **PR-1 → PR-2 → PR-3**.
 
 ## Definition of done (PR-3)
 
-- [ ] Agent guide documents exclusivity + UC10.
-- [ ] Addendum file exists and links parent propose + this plan.
-- [ ] No Python behaviour change in PR-3.
+- [x] Agent guide documents exclusivity + UC10.
+- [x] Addendum file exists and links parent propose + this plan.
+- [x] No Python behaviour change in PR-3.
 
 ---
 
@@ -243,11 +245,13 @@ Landing order: **PR-1 → PR-2 → PR-3**.
 3. No remaining `CodebaseClient` / `CodebaseClients` in production Python, tests, or fixture Java per grep contract.
 4. Completed propose addendum exists under `propose/completed/`.
 
+These criteria are met on `master` after PR-3.
+
 # Tracking
 
-- `PR-1`: _pending_
-- `PR-2`: _pending_
-- `PR-3`: _pending_
+- `PR-1`: _merged_
+- `PR-2`: _merged_
+- `PR-3`: _merged_
 
 # Optional companion
 

propose/completed/BROWNFIELD-ANNOTATIONS-V2-ADDENDUM-HTTP-METHOD-ENUM.md

@@ -0,0 +1,17 @@
+# Addendum: HTTP brownfield enum method, `@CodebaseHttpClient` rename, inbound exclusivity
+
+This file extends **[`BROWNFIELD-ANNOTATIONS-V2-PROPOSE.md`](./BROWNFIELD-ANNOTATIONS-V2-PROPOSE.md)** without editing that document’s body (immutable parent).
+
+## References
+
+- Design: [`../HTTP-ROUTE-METHOD-ENUM-PROPOSE.md`](../HTTP-ROUTE-METHOD-ENUM-PROPOSE.md)
+- Execution plan: [`../../plans/PLAN-HTTP-ROUTE-METHOD-ENUM.md`](../../plans/PLAN-HTTP-ROUTE-METHOD-ENUM.md)
+- Agent-facing summary: [`../../docs/AGENT-GUIDE.md`](../../docs/AGENT-GUIDE.md) (brownfield HTTP exclusivity subsection)
+
+## What landed (summary)
+
+- **`@CodebaseClient` / `@CodebaseClients`** renamed to **`@CodebaseHttpClient` / `@CodebaseHttpClients`** on source stubs and in the extractor; no backward-compat alias for the old simple names.
+- Shared **`CodebaseHttpMethod`** enum (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`) on both **`@CodebaseHttpRoute`** and **`@CodebaseHttpClient`** stubs; `method` is mandatory on clients and is no longer a string on the annotation surface.
+- **Inbound HTTP brownfield exclusivity:** layer-C **`@CodebaseHttpRoute`** rows **replace** same-method built-in Spring HTTP rows in merge (aligned with async behaviour); wire-format `http_method` strings remain enum `.name()` values.
+- **Structured stderr events:** **`brownfield-exclusivity-shadowing`** (INFO) on extractor co-presence of brownfield HTTP annotations with shadowable framework annotations; **`brownfield-method-string-literal`** (WARN) when `method` is still a string literal mid-migration. Merge code does not emit the INFO event (single trigger in `ast_java.py`).
+- **`ONTOLOGY_VERSION` 12**; operators should **re-index** after upgrading so `meta_chain` keys and annotation simple names match the post-rename extractor (see README “Re-index required” callouts).