Add versioned task context capsules

docs/COMPATIBILITY.md

@@ -147,6 +147,37 @@ and side-effect-free status.
 The live graph viewer remains a read-only consumer of a generation-pinned validated index. It does
 not become project authority or MCP retrieval authority.
 
+## Task-context compatibility
+
+`docforge_get_task_context` is an additive MCP read tool. The legacy `docforge_get_context`
+signature, profile compiler, direct Python results, and custom three-argument context-provider
+contract remain unchanged.
+
+The new `ContextCapsuleV1` and `RetrievalPlanV1` types live in the public
+`docforge.retrieval` submodule. Version 1 guarantees:
+
+- A closed task-kind vocabulary and core-derived plan. Callers cannot inject arbitrary operations,
+  SQL, paths, relations, or Logic requests.
+- One immutable index transaction and one exact project, adapter, revision, source, policy,
+  request, plan, collection, and capsule identity.
+- Deterministic bounded focus, traversal, hydration, token accounting, response packing, and
+  continuation, with fixed version-1 ceilings of 1,000 evidence items, 100,000 candidate edges, and
+  10,000 task-query characters.
+- Raw preservation of project-owned relation names. Only the documented versioned alias map gains
+  task semantics; all other relations remain `unclassified`.
+- Separate missing, incomplete, blocked, and provenance-limitation evidence.
+- No-AST bindings retain task context but never add a Logic retrieval step or weaken the existing
+  Logic prohibition.
+
+An integration that replaces the legacy context provider does not silently receive the core task
+planner. Version 1 has no custom task-planner protocol. The task-context tool remains registered
+for additive name compatibility but returns `task_context_unavailable` without loading or
+synchronizing the custom projection.
+
+The exact version-1 relation aliases are frozen by the MCP contract and repository contract tests.
+Changing an alias category requires a new planner version; it is not a silent implementation
+detail.
+
 `ManualRenderPlan`, `GraphViewPlan`, a portable graph renderer, and independently packaged
 renderers are later-milestone direction. Milestone 0 does not claim that those contracts exist.