feat(projectbrain): add revision-bound context compiler

[dporkka]

Summary

Adds Dev Plane's revision-bound Project Brain / Context Compiler, wires it into the agent runner behind an optional provider seam, and adds a production-safe first-party repository-intelligence source with an explicit worker rollout switch.

Project Brain contract

• source-agnostic Source interface for repo-intel/GitNexus/LSP/AST/Git/tests/runtime adapters
• normalized subject/relation/object facts with explicit provenance
• exact repository + revision filtering for revision-scoped facts
• repository-scoped facts for knowledge explicitly safe to reuse across revisions
• provenance-preserving deduplication and deterministic task-relevance ranking
• bounded context packages (24 default, 200 hard cap)
• explicit source-degradation warnings
• stable SHA-256 context-package digest; observation timestamps are excluded from context identity

First-party repo-intel source

• reuses existing packages/repo-intel; no new parser/runtime dependency
• workspace-aware source factory through WorkspaceContextCompiler
• emits revision-bound symbol-definition facts from declared changed files and task terms
• requires workspace HEAD to exactly match requested git-commit:<sha>
• requires the complete temporary-index working-tree hash to equal HEAD^{tree} before emitting facts
• dirty/mismatched workspaces fail closed through ordinary compiler warnings
• lexical indexer skips source-file symlinks
• changed paths reject traversal, absolute paths, direct symlinks, and resolved targets outside the workspace

GitNexus boundary

• retains transport-neutral GitNexusClient + GitNexusSource for symbols/relations/processes
• rejects stale GitNexus indexes by comparing requested revision to lastCommit
• GitNexus is optional and caller-supplied through agentexecutor.WithGitNexusClient
• Dev Plane does not construct, launch, distribute, or require a GitNexus runtime
• upstream GitNexus currently uses PolyForm Noncommercial 1.0.0, so it is deliberately not the required production source for this commercial-capable path
• Project Brain configuration is order-independent: EnableProjectBrain().WithGitNexusClient(client) and WithGitNexusClient(client).EnableProjectBrain() retain the same client/source set

Agent-run integration

• optional ProjectContextProvider preserves the legacy runner path when disabled
• WorkspaceProjectContextProvider extends the seam for workspace-local sources without breaking existing providers
• resolves immutable workspace HEAD before context compilation
• derives objective, acceptance criteria, and declared paths from the task contract
• validates package version/repository/revision/digest
• persists the complete ContextPackage in existing agent_runs.metadata before the first model call; no schema migration
• preserves existing metadata such as run-manifest authority
• injects selected facts as JSON Lines explicitly framed as untrusted repository observations
• raw source-warning/error text is not injected into the model prompt
• existing git-tree:<sha> remains the authority for mutable working-tree capability/verification semantics

Rollout

• agentexecutor.EnableProjectBrain() composes the first-party source
• worker activation is explicit and default-off:
  • --project-brain
  • PROJECT_BRAIN_ENABLED=true
• startup logging records whether Project Brain is enabled and the active first-party source

Evaluation path

Existing model_usage rows already reference agent_run_id, while the context package/digest is persisted on the corresponding run. This provides a joinable model/cost/context-strategy basis for later verification-outcome analysis without another telemetry schema in this slice.

TDD / regression coverage

Tests were added before corresponding behavior for:

• exact-revision filtering and repository-scoped facts
• provenance-preserving deduplication, relevance ranking, and deterministic budgets
• digest stability/invalidation
• GitNexus stale-index rejection and symbol/relation/process conversion
• task -> context-request derivation
• metadata merge preserving prior authority
• prompt-injection data boundary / JSON escaping
• disabled-provider backward compatibility
• exact workspace HEAD binding and persistence before use
• workspace/static source composition
• first-party repo-intel symbol facts
• dirty-workspace and wrong-commit rejection
• explicit GitNexus + repo-intel composition
• Project Brain/GitNexus fluent-configuration call-order independence
• worker rollout env parsing
• symlink source-file exclusion
• changed-path traversal/symlink confinement

Reconstructed verification

The repository pins go 1.26.0 / toolchain go1.26.8. The current execution container cannot resolve external hosts to download that toolchain or clone GitHub directly, so this is not claimed as repository-native Go 1.26.8 verification.

Using exact source files fetched from the connected GitHub repository and reconstructed affected modules under the available Go 1.23.2 toolchain:

• packages/projectbrain: go test, go vet, and go test -race -count=20 pass
• changed packages/repo-intel behavior: tests/vet pass and -race -count=20 passes
• Project Brain agentrunner source/security slice: tests/vet pass and -race -count=10 passes
• agentexecutor composition, including both configuration call orders: tests/vet pass and -race -count=20 passes
• worker Project Brain env parsing: tests/vet pass and -race -count=50 passes

This gives executable evidence for the changed logic, but the PR remains draft until the checked-in Go 1.26.8 lane actually executes the exact head.

CI evidence

On exact head 7ae6592455fdf37690686714f809126521b38e6e, GitHub Actions CI run #648 created Build/Test/Lint. All three failed before any step executed: runner_id=0, steps=[], with completion in roughly 1-2 seconds. This is workflow-admission/runner evidence rather than code-execution evidence.

Scope / boundaries

• no database migration
• no model-router change
• no browser-verification change
• no required external graph/database service
• no implicit GitNexus process/network dependency
• Project Brain remains default-off at the worker boundary

Next integration

1. Execute exact head 7ae6592455fdf37690686714f809126521b38e6e in the authoritative Go 1.26.8 lane, then enable Project Brain for a small local-workspace cohort.
2. Add a stronger permissively licensed first-party semantic source (LSP/tree-sitter) behind the existing Source contract.
3. Join context identity with model usage and verified outcomes to measure context/routing policy empirically.
4. Add runtime/deployment facts only after source-code context has production evidence.

This remains intentionally separate from the browser-verification, Nulang Cloud workspace, semantic model-routing, run-manifest, and repository-protocol stacks.