feat(code): add Git repository context to prepare_context

[Teingi]

Which issue or RFC does this PR close?

Implements the first-phase design in RFC #1619.

Rationale for this change

When an agent resumes a coding task, historical Memory and Handoff material can explain decisions without showing the current implementation. This change lets prepare_context(include_code=True) add current Python definitions and bounded structural relationships alongside historical context, under one entry and byte budget.

What changes are included in this PR?

• Add an optional CodeGraph 1.6.0 adapter, explicit local powercontext code index/status commands, and a configured mapping from existing Scopes to Git directories. The index is a rebuildable local cache; no new artifact family, workspace entity, or database table is introduced.
• Capture the working tree with content fingerprints, validate freshness before delivery, publish complete cache generations atomically, and enforce path, authorization, time, size, and subprocess boundaries. Raw Git capture avoids running repository clean filters.
• Add include_code to context preparation, share the existing assembly budget, and retain historical context when code is unavailable or changes during preparation. Normal preparation does not persist code as Sources or Artifacts.
• Add the HTTP/SDK code-query API and the read-only powercontext_code_query MCP tool for status, tree, symbols, callers, callees, impact, affected tests, and bounded source reads. Continuation queries validate the expected fingerprint.
• Support opt-in Codex injection with older-Server fallback. Explicitly saved code-query Sources remain readable as evidence but are excluded from automatic Memory/Experience/TopicMemory/Profile processing.
• Add bilingual usage documentation, real-engine regression tests, and opt-in configured-service and native Codex acceptance tests.

Are there any user-facing changes?

The feature is disabled by default. Deployments opt in by configuring a local repository and the separately installed CodeGraph executable, building its index explicitly, and enabling code context for requests or the Codex integration. Existing requests retain their default behavior; there is no database migration.

The initial implementation supports local Python repositories. Refresh is explicit, cache operations use a cache-wide lock, and static relationships are incomplete. Ambiguous same-name relationships are rejected or omitted. The usage guide documents these limits and the supported engine build.

The 12-task paired evaluation ran both settings twice (48 real model runs). Correct definition-file sets were 22/24 without code and 23/24 with code; caller sets were 20/24 and 22/24. All 16 patch checks and 48 regression checks passed. Median end-to-end time increased from 16.32 s to 22.36 s and median input tokens for completed outputs increased from 6,097.5 to 14,240. These small fixture results support keeping the feature opt-in; they do not establish an efficiency gain or justify reducing tests.

How was this change tested?

• make check: passed, including type checks. Pre-commit hooks also passed over all 80 changed files, including new files.
• make contract-test: 48 passed.
• make docs-test: passed; verified 811 public pages and internal links.
• Real CodeGraph/Git/HTTP regression run: 18 passed. Final Git capture/process checks: 10 passed, including clean filters, branch changes, SHA256 repositories, and child-process cleanup. The final context-statistics regression passed separately.
• The full non-E2E run initially reported 2,362 passed, 53 skipped, and 7 failures. Tool metadata/manifest issues were fixed; host checks were rerun with supported Node 24 and CLI checks with inherited test configuration cleared. The affected-module rerun had 155 passed, 1 skipped, and 2 remaining manifest ordering failures; the subsequent manifest suite passed all 28 tests after the ordering fix. A second full-suite run was not performed.
• POWERCONTEXT_TEST_NATIVE_CODEX=1 uv run pytest tests/e2e/real_experience_skill/test_code_context.py --run-real-e2e --real-e2e-env-file .env -q -s, with POWERCONTEXT_TEST_CODEGRAPH_EXECUTABLE pointing to the installed engine: passed in 305.81 s. This used the configured OceanBase, LLM and embedding services, actual HTTP/SDK/MCP paths, and native Codex. It verified repair, executable checks, Handoff continuation after a code change, refreshed fingerprints, explicit Source retention after cache removal, automatic-processing exclusion, and subsequent ordinary Source processing. The temporary database was removed and user Codex state was unchanged.
• Real PowerContext repository probe: 791 Python files indexed in 28.476 s; three prepare queries completed in 4.467/2.695/3.684 s. This is an observed single-host result, not a latency guarantee.
• One-off paired evaluation: 48 configured-model runs, with results, failures, and usage-coverage limits summarized above. Experiment scripts and run reports are kept outside the source tree.
• Wheel build passed; the package includes the engine bridge and CLI entry point. Credentials, downloaded engine binaries, caches, and local test reports are excluded from the commit.

Real engine and configured-service tests require explicit local setup and are skipped when their prerequisites are absent. Local validation does not imply that upstream CI has completed.

AI usage statement

Implemented and tested with OpenAI Codex (GPT-6), including code generation, test development, documentation, and command execution. The paired task evaluation used the configured openai:qwen3.7-plus model. Results and limitations are summarized in this PR.

[Teingi]

I reproduced the four issues below on 250a247 using real CodeGraph 1.6.0 and Git fixtures, plus SQLite/HTTP checks for context preparation. OceanBase and native Codex acceptance were not rerun in this review.