From ac69a086e7e6201639989d67a7be96840664f326 Mon Sep 17 00:00:00 2001 From: ivkond Date: Sun, 19 Apr 2026 17:31:26 +0300 Subject: [PATCH] docs(#794): align AGENTS.md and ARCHITECTURE.md with @ MCP routing The PR #984 reviewer flagged that both top-level docs still listed the removed `group_query`, `group_contracts`, and `group_status` MCP tools. Bring them in line with the actual MCP surface introduced by #794: - `AGENTS.md` Tools Quick Reference now lists `query`/`context`/`impact` in group mode (`repo: "@"`) and drops the three removed group_* tools. Adds the two new resources (`gitnexus://group/{name}/contracts` + `/status`) to the Resources table and a 1.5.0 changelog entry. - `ARCHITECTURE.md` MCP tools table is trimmed to `group_list` and `group_sync`, with a paragraph + resource table describing the group-aware behaviour of `query`/`context`/`impact` and the bridge fan-out for cross-repo impact. "Where to change what" now points at `src/core/group/` for cross-repo work. Made-with: Cursor --- AGENTS.md | 11 ++++++++--- ARCHITECTURE.md | 13 +++++++++---- 2 files changed, 17 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f4fbcadc0..6e916ff0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,7 @@ Commands and gotchas live under **Repo reference** below and in **[CONTRIBUTING. | Date | Version | Change | |------|---------|--------| +| 2026-04-19 | 1.5.0 | Cross-repo impact (#794): `impact`/`query`/`context` accept `repo: "@"` + `service`. Removed `group_query`/`group_contracts`/`group_status` MCP tools; added `gitnexus://group/{name}/contracts` and `gitnexus://group/{name}/status` resources. | | 2026-04-16 | 1.4.0 | Fixed: web UI description, pre-commit behavior, MCP tools (7->16), added gitnexus-shared, removed stale vite-plugin-wasm gotcha. | | 2026-04-13 | 1.3.0 | Updated GitNexus index stats after DAG refactor. | | 2026-03-24 | 1.2.0 | Fixed gitnexus:start block duplication. | @@ -107,10 +108,12 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows) | `tool_map` | MCP/RPC tool definitions | `gitnexus_tool_map({})` | | `shape_check` | Response shape vs consumer access | `gitnexus_shape_check({route: "/api/users"})` | | `group_list` | List repo groups | `gitnexus_group_list({})` | -| `group_query` | Cross-repo search in a group | `gitnexus_group_query({name: "myGroup", query: "auth"})` | | `group_sync` | Rebuild group Contract Registry | `gitnexus_group_sync({name: "myGroup"})` | -| `group_contracts` | Inspect group contracts | `gitnexus_group_contracts({name: "myGroup"})` | -| `group_status` | Group staleness report | `gitnexus_group_status({name: "myGroup"})` | +| `query` (group mode) | Cross-repo search in a group (RRF-merged) | `gitnexus_query({repo: "@myGroup", query: "auth"})` | +| `context` (group mode) | 360° view across all member repos | `gitnexus_context({repo: "@myGroup", name: "validateUser"})` | +| `impact` (group mode) | Cross-repo blast radius via Contract Bridge | `gitnexus_impact({repo: "@myGroup", target: "X", direction: "upstream"})` | + +> Group mode: pass `repo: "@"` to fan out across all member repos, or `repo: "@/"` to target a single member (path keys from `group.yaml`). Optional `service: ""` filters by service root. Group-level state (contracts, staleness) lives in the resources table below — there are **no** `group_query` / `group_context` / `group_impact` / `group_contracts` / `group_status` MCP tools. ## Impact Risk Levels @@ -128,6 +131,8 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows) | `gitnexus://repo/GitNexus/clusters` | All functional areas | | `gitnexus://repo/GitNexus/processes` | All execution flows | | `gitnexus://repo/GitNexus/process/{name}` | Step-by-step execution trace | +| `gitnexus://group/{name}/contracts` | Group Contract Registry (provider/consumer rows + cross-links) | +| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness report | ## Self-Check Before Finishing diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index d934cd8b6..ceb2f9583 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -42,10 +42,14 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`). | `tool_map` | MCP/RPC tool definitions and handlers | | `shape_check` | Response shape vs consumer property access mismatches | | `group_list` | List repo groups or details for one group | -| `group_query` | Cross-repo search in a group (reciprocal rank fusion) | -| `group_sync` | Rebuild group Contract Registry (`contracts.json`) | -| `group_contracts` | Inspect group contracts and cross-links | -| `group_status` | Index and Contract Registry staleness per repo in a group | +| `group_sync` | Rebuild group Contract Registry (`contracts.json`) and bridge graph | + +`query`, `context`, and `impact` are group-aware: pass `repo: "@"` (or `"@/"` to scope to one member) plus optional `service: ""`. Group-mode `query` merges per-repo results via Reciprocal Rank Fusion; group-mode `impact` runs the local walk in the chosen member and fans out across boundaries via the Contract Bridge (`gitnexus/src/core/group/cross-impact.ts`). The previously-planned `group_query`, `group_context`, `group_impact`, `group_contracts`, `group_status` MCP tools are intentionally not introduced — group-level state is exposed via resources instead: + +| Resource URI | Purpose | +|--------------|---------| +| `gitnexus://group/{name}/contracts` | Contract Registry (provider/consumer rows + cross-links) | +| `gitnexus://group/{name}/status` | Per-member index + Contract Registry staleness | ## Where to change what @@ -55,6 +59,7 @@ Monorepo: **CLI/MCP** (`gitnexus/`) + **browser UI** (`gitnexus-web/`). | Parsing/graph construction | `src/core/ingestion/pipeline-phases/` + `pipeline.ts` | | Graph schema/DB | `src/core/lbug/` (`schema.ts`, `lbug-adapter.ts`) | | MCP tools/resources | `src/mcp/server.ts`, `tools.ts`, `resources.ts` | +| Cross-repo groups (sync, contracts, `@` routing) | `src/core/group/` (`service.ts`, `cross-impact.ts`, `sync.ts`, `bridge-db.ts`) | | Search ranking | `src/core/search/` (BM25, hybrid fusion) | | Embeddings | `src/core/embeddings/` + `src/core/run-analyze.ts` | | Wiki generation | `src/core/wiki/` |