feat: cross-namespace refs — materialized ccg:// links, federated reads, cross-repo analysis

.gitignore

@@ -29,3 +29,4 @@ pyproject.toml
 /container-artifacts/
 search-retrieval.md
 _workspace/
+/artifacts/

CLAUDE.md

@@ -5,11 +5,11 @@
 Follow the global prompt rules first. This file adds project-specific skill routing for a project that uses the `agent-team` CLI (github.com/tae2089/agent-team) as its durable work ledger.
 
 ## MCP 서버
-`.mcp.json`에 등록된 ccg MCP 서버가 17개 도구를 제공합니다:
+`.mcp.json`에 등록된 ccg MCP 서버가 18개 도구를 제공합니다:
 
 - `parse_project`, `build_or_update_graph`, `run_postprocess`
 - `get_node`, `search`, `query_graph`, `list_graph_stats`, `list_namespaces`, `get_minimal_context`
-- `get_impact_radius`, `trace_flow`
+- `get_impact_radius`, `trace_flow`, `list_cross_refs`
 - `detect_changes`, `get_affected_flows`, `list_flows`
 - `get_annotation`
 - `get_doc_content`, `search_docs`
@@ -45,7 +45,7 @@ Graceful shutdown: SIGINT/SIGTERM 시 진행 중인 clone/build에 context cance
 상세 문서는 `guide/` 디렉토리를 참조하세요:
 
 - [CLI Reference](guide/cli-reference.md) — 전체 명령어, 플래그, 설정 파일
-- [MCP Tools](guide/mcp-tools.md) — 17개 MCP 도구, Skills, AI-Driven Annotation
+- [MCP Tools](guide/mcp-tools.md) — 18개 MCP 도구, Skills, AI-Driven Annotation
 - [Annotations](guide/annotations.md) — 어노테이션 태그, 예시, 검색
 - [Webhook](guide/webhook.md) — Webhook sync, 브랜치 필터링, HMAC, graceful shutdown
 - [Docker](guide/docker.md) — Docker 빌드, MCP 서버, PostgreSQL 배포

docker-compose.integration.yml

@@ -67,7 +67,7 @@ services:
       - --http-bearer-token=test-mcp-token
       - --db-driver=postgres
       - --db-dsn=host=postgres user=ccg password=ccg dbname=ccg_integration port=5432 sslmode=disable
-      - --allow-repo=*/*
+      - --allow-repo=testadmin/*
       - --webhook-secret=test-webhook-secret
       - --repo-clone-base-url=http://gitea:3000
       - --repo-root=/repos

guide/README.md

@@ -20,7 +20,7 @@ explore graph edges.
 |----------|-------------|
 | [CLI Reference](cli-reference.md) | Full CLI commands, options, and configuration file (`.ccg.yaml`) |
 | [Lint](lint.md) | Detailed `ccg lint` category reference, interpretation guide, and CI usage |
-| [MCP Tools](mcp-tools.md) | 17 MCP tools, agent skills, evidence-first routing, AI-driven annotation |
+| [MCP Tools](mcp-tools.md) | 18 MCP tools, agent skills, evidence-first routing, AI-driven annotation |
 | [Annotations](annotations.md) | Custom annotation system — tags, examples, and search quality |
 | [Webhook](webhook.md) | GitHub / Gitea webhook sync, branch filtering, graceful shutdown |
 | [Docker](docker.md) | Docker image build, MCP server setup, Wiki UI deployment, PostgreSQL integration |

guide/annotations.md

@@ -62,6 +62,8 @@ Use `ccg://{namespace}/{path}#{symbol}` in `@see` when a behavior depends on cod
 
 The path and symbol are optional, so `ccg://auth-svc/internal/auth` can point at a package/path scope and `ccg://auth-svc/` can point at a whole namespace.
 
+Every `@see ccg://` tag is materialized into the `cross_refs` table after each build or update: the target is resolved against the referenced namespace's current nodes and the row is marked `resolved` or `dead`. When either side rebuilds, refs are re-resolved automatically, so a `dead` ref recovers as soon as the target symbol appears. Materialized refs power `list_cross_refs` (repository dependency map) and the `cross_namespace: true` mode of `get_impact_radius`/`trace_flow`. Namespace-scope refs (`ccg://auth-svc/`) resolve without a node target and never appear in traversal, only in listings.
+
 ## Retrieval Quality
 
 Annotations are retrieval features. `search_docs` and generated docs rank

guide/architecture.md

@@ -62,7 +62,7 @@ closure with deterministic `go list -json` checks.
 ## Runtime and transports
 
 Both `ccg serve` (stdio) and `ccg-server` (Streamable HTTP) use the same five
-grouped MCP dependency surfaces and expose exactly 17 tools plus four prompts.
+grouped MCP dependency surfaces and expose exactly 18 tools plus four prompts.
 The local binary does not link remote HTTP, Wiki, webhook, or remote runtime
 packages. See [Runtime Layout](runtime-layout.md).
 
@@ -74,6 +74,16 @@ filters. SQLite and PostgreSQL share GORM-owned graph operations and backend-
 specific full-text search adapters. Application and inbound packages never issue
 SQL; backend-specific SQL remains encapsulated in outbound adapters and migration code.
 
+The `cross_refs` table is the one deliberate bridge across namespaces: each row
+materializes an `@see ccg://` annotation with a symbolic target
+(`to_namespace`, `to_path`, `to_symbol`) plus derived state
+(`resolved_node_id`, `status`). Rows are rebuilt from annotations after every
+build/update of the source namespace and re-resolved when the target namespace
+rebuilds, because replace-style syncs regenerate node ids. Cross-namespace
+analysis reads go through a dedicated namespace-agnostic reader that merges
+resolved refs into traversal as synthetic `cross_ref` edges; regular
+single-namespace query paths remain strictly namespace-filtered.
+
 ## Reliability and security
 
 - Repository sync verifies HMAC before trust, applies ordered allow rules, bounds

guide/development.md

@@ -103,7 +103,7 @@ internal/
   ctx/                — Request-context values (namespace isolation)
   docs/               — Documentation generation
   mcpruntime/         — Shared MCP runtime assembly, stdio runner, cache, telemetry
-  mcp/                — MCP server (17 tools)
+  mcp/                — MCP server (18 tools)
   wikiserver/         — ccg-server Wiki static serving and viewer API
   wikiindex/          — Wiki presentation index builder (`wiki-index.json`)
   model/              — DB models

guide/ko/README.md

@@ -23,7 +23,7 @@ DB-backed graph/annotation evidence를 사용하며, 시각적 Graph 탭은
 |------|------|
 | [CLI 레퍼런스](cli-reference.md) | 모든 CLI 명령어, 옵션 및 설정 파일(`.ccg.yaml`) 안내 |
 | [Lint](lint.md) | `ccg lint` 카테고리 상세 레퍼런스, 결과 해석 및 CI 활용법 |
-| [MCP 도구](mcp-tools.md) | 17개의 MCP 도구, 에이전트 스킬, evidence-first 라우팅, AI 기반 어노테이션 |
+| [MCP 도구](mcp-tools.md) | 18개의 MCP 도구, 에이전트 스킬, evidence-first 라우팅, AI 기반 어노테이션 |
 | [어노테이션](annotations.md) | 커스텀 어노테이션 시스템 — 태그, 예시, 검색 품질 |
 | [웹훅(Webhook)](webhook.md) | GitHub / Gitea 웹훅 동기화, 브랜치 필터링, Graceful Shutdown |
 | [Docker](docker.md) | Docker 이미지 빌드, MCP 서버 설정, Wiki UI 배포, PostgreSQL 연동 |

guide/ko/architecture.md

@@ -60,7 +60,7 @@ CLI / MCP / HTTP / Wiki / webhook -> application capability -> outbound port
 ## 런타임과 전송 계층
 
 `ccg serve`(stdio)와 `ccg-server`(Streamable HTTP)는 동일한 다섯 MCP 의존성
-그룹을 사용하며 정확히 17개 tool과 4개 prompt를 노출합니다. 로컬 바이너리는
+그룹을 사용하며 정확히 18개 tool과 4개 prompt를 노출합니다. 로컬 바이너리는
 원격 HTTP, Wiki, webhook, remote runtime 패키지를 링크하지 않습니다.
 자세한 내용은 [런타임 레이아웃](runtime-layout.md)을 참고하세요.
 

guide/ko/development.md

@@ -105,7 +105,7 @@ internal/
   ctx/                — 요청 컨텍스트 값 (namespace 격리)
   docs/               — 문서 생성 로직
   mcpruntime/         — 공용 MCP runtime assembly, stdio runner, cache, telemetry
-  mcp/                — MCP 서버 (17개 도구)
+  mcp/                — MCP 서버 (18개 도구)
   wikiserver/         — ccg-server Wiki 정적 파일 서빙 및 viewer API
   wikiindex/          — Wiki 표시용 인덱스 생성기 (`wiki-index.json`)
   model/              — DB 모델

guide/ko/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP 도구
 
-code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타임 모두에서 17개의 MCP 도구를 제공합니다.
+code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타임 모두에서 18개의 MCP 도구를 제공합니다.
 
 ## 파싱 및 빌드
 
@@ -15,27 +15,28 @@ code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타
 | 도구 | 용도 |
 | ---- | ---- |
 | `get_node` | qualified name으로 node 하나 조회 |
-| `search` | path scope를 선택적으로 적용하는 code node full-text search |
+| `search` | path scope를 선택적으로 적용하는 code node full-text search; `namespaces: []`로 여러 namespace 연합 검색 (결과에 namespace 라벨) |
 | `get_annotation` | node의 annotation과 문서 tag 조회 |
-| `query_graph` | callers, callees, imports, children, tests, inheritors, file summary 조회 |
-| `list_graph_stats` | node와 edge를 kind 및 language별로 집계 |
+| `query_graph` | callers, callees, imports, children, tests, inheritors, file summary 조회; `namespaces: []`는 namespace별 그룹 응답 |
+| `list_graph_stats` | node와 edge를 kind 및 language별로 집계; `namespaces: []`는 namespace별 그룹 응답 |
 | `list_namespaces` | graph data가 있는 namespace와 node count 목록 조회 |
 
 ## 분석
 
 | 도구 | 용도 |
 | ---- | ---- |
-| `get_impact_radius` | node 주변의 제한된 BFS 영향 반경 계산 |
-| `trace_flow` | node에서 시작하는 제한된 call chain 추적 |
+| `get_impact_radius` | node 주변의 제한된 BFS 영향 반경 계산; `cross_namespace: true`면 resolved `ccg://` ref를 양방향으로 통과 |
+| `trace_flow` | node에서 시작하는 제한된 call chain 추적; `cross_namespace: true`면 resolved `ccg://` ref를 넘어 계속 추적 |
 | `detect_changes` | git diff 기반 변경 함수 탐지 및 risk score 계산 |
 | `get_affected_flows` | 최근 변경의 영향을 받는 저장 flow 조회 |
 | `list_flows` | 저장 flow를 페이지네이션해 조회 |
+| `list_cross_refs` | 실체화된 `ccg://` cross-namespace 참조 목록 (direction: outbound/inbound/both, status 필터) |
 
 ## 문서 및 컨텍스트
 
 | 도구 | 용도 |
 | ---- | ---- |
-| `search_docs` | DB-backed 문서 후보와 graph evidence 검색 |
+| `search_docs` | DB-backed 문서 후보와 graph evidence 검색; `namespaces: []`는 namespace별 그룹 응답 |
 | `get_doc_content` | 선택한 생성 Markdown 파일을 안전하게 읽기 |
 | `get_minimal_context` | 작은 프로젝트/변경 요약과 다음 도구 제안 반환 |
 
@@ -51,4 +52,4 @@ code-context-graph는 로컬 `ccg serve`와 셀프호스트 `ccg-server` 런타
 
 `query_graph`와 `list_flows`에는 명시적인 `limit`, `offset`을 사용하십시오. 50 또는 100개로 시작하고 페이지네이션 metadata를 따라 확장합니다.
 
-로컬 MCP client는 stdio 방식의 `ccg serve`를 시작하고, 원격 client는 `ccg-server`의 `/mcp` Streamable HTTP endpoint에 연결합니다. 두 런타임은 동일한 17개 도구를 등록합니다.
+로컬 MCP client는 stdio 방식의 `ccg serve`를 시작하고, 원격 client는 `ccg-server`의 `/mcp` Streamable HTTP endpoint에 연결합니다. 두 런타임은 동일한 18개 도구를 등록합니다.

guide/ko/runtime-layout.md

@@ -29,7 +29,7 @@ HTTP host, Wiki HTTP, webhook adapter, remote runtime은 링크하지 않습니
 - `/wiki`, `/wiki/api/*` — 선택적인 CCG 내장 Wiki
 - `/webhook` — 선택적인 GitHub/Gitea repository sync
 
-두 transport 모두 `Runtime.MCPComponents()`를 사용하므로 동일한 17개 tool과
+두 transport 모두 `Runtime.MCPComponents()`를 사용하므로 동일한 18개 tool과
 4개 prompt를 등록합니다.
 
 ## 리소스 소유권

guide/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP Tools
 
-code-context-graph exposes 17 MCP tools through both local `ccg serve` and the self-hosted `ccg-server` runtime.
+code-context-graph exposes 18 MCP tools through both local `ccg serve` and the self-hosted `ccg-server` runtime.
 
 ## Parse and Build
 
@@ -15,27 +15,28 @@ code-context-graph exposes 17 MCP tools through both local `ccg serve` and the s
 | Tool | Purpose |
 | ---- | ------- |
 | `get_node` | Read one node by qualified name |
-| `search` | Full-text search across code nodes, optionally scoped by path |
+| `search` | Full-text search across code nodes, optionally scoped by path; `namespaces: []` federates across namespaces with per-item labels |
 | `get_annotation` | Read annotations and documentation tags for one node |
-| `query_graph` | Run callers, callees, imports, children, tests, inheritors, or file-summary queries |
-| `list_graph_stats` | Report node and edge counts by kind and language |
+| `query_graph` | Run callers, callees, imports, children, tests, inheritors, or file-summary queries; `namespaces: []` groups results per namespace |
+| `list_graph_stats` | Report node and edge counts by kind and language; `namespaces: []` returns per-namespace groups |
 | `list_namespaces` | List namespaces that contain graph data and their node counts |
 
 ## Analysis
 
 | Tool | Purpose |
 | ---- | ------- |
-| `get_impact_radius` | Compute a bounded BFS blast radius around a node |
-| `trace_flow` | Trace a bounded call chain from a node |
+| `get_impact_radius` | Compute a bounded BFS blast radius around a node; `cross_namespace: true` follows resolved `ccg://` refs both ways |
+| `trace_flow` | Trace a bounded call chain from a node; `cross_namespace: true` continues across resolved `ccg://` refs |
 | `detect_changes` | Detect changed functions from git diff and calculate risk scores |
 | `get_affected_flows` | List stored flows affected by recent changes |
 | `list_flows` | List stored flows with bounded pagination |
+| `list_cross_refs` | List materialized `ccg://` cross-namespace references (direction: outbound/inbound/both, status filter) |
 
 ## Documentation and Context
 
 | Tool | Purpose |
 | ---- | ------- |
-| `search_docs` | Search DB-backed documentation candidates and graph evidence |
+| `search_docs` | Search DB-backed documentation candidates and graph evidence; `namespaces: []` groups results per namespace |
 | `get_doc_content` | Safely read a selected generated Markdown file |
 | `get_minimal_context` | Return a compact project/change summary and suggested next tools |
 
@@ -53,6 +54,6 @@ Use explicit `limit` and `offset` values for `query_graph` and `list_flows`. Sta
 
 ## Runtime
 
-Local MCP clients start `ccg serve` over stdio. Remote clients connect to the `/mcp` Streamable HTTP endpoint served by `ccg-server`. Both runtimes register the same 17 tools.
+Local MCP clients start `ccg serve` over stdio. Remote clients connect to the `/mcp` Streamable HTTP endpoint served by `ccg-server`. Both runtimes register the same 18 tools.
 
 For tool parameters and response schemas, inspect the MCP schema exposed by the running server; source registration lives under `internal/adapters/inbound/mcp/tools_*.go`.

guide/runtime-layout.md

@@ -31,7 +31,7 @@ runtime. This keeps local MCP use independent of remote hosting policy.
 - `/webhook` — optional GitHub/Gitea repository sync
 
 Both transports call `Runtime.MCPComponents()` and therefore register the same
-17 tools and four prompts.
+18 tools and four prompts.
 
 ## Resource ownership
 

internal/adapters/inbound/cli/build.go

@@ -7,6 +7,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/tae2089/trace"
 
+	"github.com/tae2089/code-context-graph/internal/app/crossref"
 	"github.com/tae2089/code-context-graph/internal/app/ingest"
 	"github.com/tae2089/code-context-graph/internal/app/ingest/workflow"
 	requestctx "github.com/tae2089/code-context-graph/internal/ctx"
@@ -47,6 +48,9 @@ func newBuildCmd(deps *Deps) *cobra.Command {
 				Walkers:    deps.Walkers,
 				Logger:     deps.Logger,
 			}
+			if crossRefStore, ok := deps.Store.(crossref.Store); ok {
+				svc.CrossRefs = crossref.New(crossRefStore)
+			}
 
 			opts := workflow.BuildOptions{
 				Dir:                 dir,

internal/adapters/inbound/cli/update.go

@@ -6,6 +6,7 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/tae2089/trace"
 
+	"github.com/tae2089/code-context-graph/internal/app/crossref"
 	"github.com/tae2089/code-context-graph/internal/app/ingest"
 	"github.com/tae2089/code-context-graph/internal/app/ingest/workflow"
 	requestctx "github.com/tae2089/code-context-graph/internal/ctx"
@@ -50,6 +51,9 @@ func newUpdateCmd(deps *Deps) *cobra.Command {
 				Walkers:    deps.Walkers,
 				Logger:     deps.Logger,
 			}
+			if crossRefStore, ok := deps.Store.(crossref.Store); ok {
+				svc.CrossRefs = crossref.New(crossRefStore)
+			}
 			stats, err := svc.Update(ctx, workflow.UpdateOptions{
 				BuildOptions: workflow.BuildOptions{
 					Dir:                 dir,

internal/adapters/inbound/mcp/deps.go

@@ -109,13 +109,24 @@ type GraphToolsDeps struct {
 	Reader     analyze.GraphReadRepository
 }
 
+// CrossRefLister exposes materialized cross-namespace references for listing tools.
+// @intent let handlers enumerate repository-level dependencies without a store implementation dependency.
+type CrossRefLister interface {
+	ListOutboundCrossRefs(ctx context.Context, fromNamespace string) ([]graph.CrossRef, error)
+	ListInboundCrossRefs(ctx context.Context, toNamespace string) ([]graph.CrossRef, error)
+}
+
 // AnalysisToolsDeps owns bounded impact, flow, and git-change analysis dependencies.
 // @intent group only configured application analyzers and their read-model port.
+// @domainRule CrossImpact/CrossFlow/CrossRefs are optional; when nil the cross-namespace analysis surface reports itself unconfigured.
 type AnalysisToolsDeps struct {
-	Impact  ImpactAnalyzer
-	Flow    FlowTracer
-	Changes ChangeAnalyzer
-	Reader  analyze.GraphReadRepository
+	Impact      ImpactAnalyzer
+	Flow        FlowTracer
+	Changes     ChangeAnalyzer
+	Reader      analyze.GraphReadRepository
+	CrossImpact ImpactAnalyzer
+	CrossFlow   FlowTracer
+	CrossRefs   CrossRefLister
 }
 
 // DocsToolsDeps owns DB-primary documentation retrieval.