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.
 

docs/CONTRACT.md

@@ -18,7 +18,9 @@ commit when Git is available; it cannot change repository state.
 - Edge schema: `schemas/edge.schema.json`, version 1.
 - Result envelope: `schemas/result.schema.json`, version 1.
 - Changeset schema: `schemas/changeset.schema.json`, version 1.
-- Index schema: version 2, disposable and reproducible.
+- Effective policy: `schemas/policy.schema.json`, version 1.
+- Task context capsule: `schemas/context-capsule.schema.json`, version 1.
+- Index schema: version 3, disposable and reproducible.
 - Index attestation: schema version 1, disposable and reproducible.
 - Core, CLI, and MCP server: version 1.3.0.dev0.
 - Incremental extraction cache: version 1, disposable and reproducible.
@@ -44,6 +46,12 @@ source hash. Errors use a stable code, direct message, structured details, and a
 tool when recovery is safe. MCP operations synchronize disposable index state under a project lock
 before reading or proposing. Canonical source validation remains fail-closed.
 
+Task-context retrieval derives a closed version-1 plan from a bounded task kind and the effective
+process policy. It executes against one immutable index transaction and returns generation-bound,
+hash-identified evidence, gaps, omissions, and provenance limitations. Project relation names
+remain authoritative. The core applies task semantics only to its versioned alias set and preserves
+every other allowed relation as unclassified.
+
 An atomic index build writes a whole-file SHA-256 attestation after complete graph, row, FTS, and
 SQLite integrity verification. A fresh process may use that receipt to verify an unchanged index
 without reconstructing all graph rows. A missing, malformed, or mismatched receipt falls back to
@@ -94,9 +102,10 @@ renderers. Render identity covers the canonical source hash, optional changeset
 and edge identities, view configuration, template hash, renderer contract, and exact parser version.
 
 An explicit CLI render atomically replaces one declared derived output. MCP can render a validated
-changeset only to its isolated preview path. Status recomputes expected output without writing and
-reports `current`, `stale`, `missing`, `unsafe`, or `oversized`. Input changes detected before atomic
-replacement fail without replacing the prior output.
+changeset only to its isolated preview path. Normal status verifies bounded source, configuration,
+template, output, renderer, and publication-receipt identities without reconstructing the output.
+Explicit deep status remains the side-effect-free full-render oracle. Input changes detected before
+atomic replacement fail without publishing a current receipt for stale output.
 
 Normal MCP access does not expose canonical application. An explicitly configured canonical
 applier registers one hash-bound application tool. No MCP mode exposes arbitrary renderer

docs/MCP_CONTRACT.md

@@ -42,6 +42,7 @@ schema version 1 and does not silently acquire machine-specific process policy.
 - `docforge_dependencies`
 - `docforge_impact`
 - `docforge_get_context`
+- `docforge_get_task_context`
 - `docforge_validate_project`
 - `docforge_render_status`
 - `docforge_visualize`
@@ -72,6 +73,46 @@ oversized entry advances as a hash-identified `response size limit` omission so
 loop; targeted retrieval remains available for that node. The existing three-argument custom
 context-provider contract is unchanged because pagination is applied after provider selection.
 
+`docforge_get_task_context` accepts one closed task kind (`change`, `implementation`, `failure`,
+`ownership`, `test`, `operation`, or `release`), a bounded task description, and optional
+`focus_node_id`, token `budget`, page `limit`, and opaque `cursor`. It derives, rather than accepts,
+a version-1 retrieval plan. The plan contains only exact or lexical focus, bounded outgoing and
+incoming graph traversal, and metadata hydration. It cannot request arbitrary SQL, paths, relation
+names, or Logic extraction. Task context applies fixed internal ceilings of 1,000 evidence items,
+100,000 examined candidate edges, and 10,000 task-query characters even when broader project
+limits are configured. Traversal steps bind the complete project-owned relation vocabulary by hash
+rather than copying an unbounded name list into every response.
+
+The plan and returned context capsule are bound to the effective policy and one immutable index
+generation. Every evidence item identifies its indexed source path, content hash, graph path,
+additional qualifying relationship reasons, and the provenance facts that the current graph
+cannot prove. Required evidence gaps distinguish an undeclared relation category, a completed
+bounded search with no selected evidence, and an incomplete proof caused by a work, result, token,
+or response limit. Unknown project relations remain present with their raw names and an
+`unclassified_relation` limitation; DocForge never infers semantics from spelling outside the
+versioned alias map.
+
+Path relationship direction is relative to the preceding traversal node. Additional
+`relationship_reasons` direction is relative to the evidence item itself: `outgoing` when that
+evidence node is the stored source and `incoming` when it is the stored target.
+
+The exact version-1 aliases are: structure (`contains`, `defined_in`, `defines`, `owns`);
+implementation (`implemented_by`, `implements`, `inherits`, `inherits_from`); dependency
+(`depends_on`, `imports`); execution (`activates`, `calls`, `dispatches_to`, `launches`); data
+(`reads`, `writes`); evidence (`documents`, `governs`, `proves`, `tested_by`, `verifies`); and
+context (`relates_to`). Every other allowed relation is `unclassified`.
+
+Task-context continuation partitions the immutable evidence stream without changing its
+`request_hash`, `plan_hash`, `collection_hash`, or `capsule_hash`. Its cursor additionally binds
+the effective policy and task request. One evidence item that cannot fit advances exactly once as
+a hash-identified `response_limit` omission. A changed generation, policy, plan, or collection
+fails as `stale_cursor`.
+
+The legacy `docforge_get_context` tool and its custom three-argument provider contract remain
+unchanged. A server with a custom context provider does not silently inherit the core task planner;
+version 1 exposes no custom task-planner extension point. `docforge_get_task_context` returns
+`task_context_unavailable` without synchronizing or loading the custom projection.
+
 Version-1 cursors are canonical JSON encoded as base64url with a domain-separated SHA-256
 corruption checksum. They are opaque and fail closed, but are not authenticated authorization
 tokens. Cursors bind the project, adapter, source generation, operation parameters, collection

docs/USER_MANUAL.md

@@ -582,6 +582,7 @@ Example MCP client configuration:
 - `docforge_dependencies`
 - `docforge_impact`
 - `docforge_get_context`
+- `docforge_get_task_context`
 - `docforge_validate_project`
 - `docforge_render_status`
 - `docforge_visualize`
@@ -613,6 +614,36 @@ The application call requires `changeset_id` and `expected_changeset_hash`. Alwa
 inspect the final diff after the last proposal mutation. Apply that exact hash. A proposal mutation
 creates a new hash, so an earlier approval cannot silently apply later content.
 
+Use `docforge_get_task_context` when an agent needs one bounded task-shaped intake instead of a
+named profile. Choose `task_kind` from `change`, `implementation`, `failure`, `ownership`, `test`,
+`operation`, or `release`. Supply `focus_node_id` when the stable node is known. Without it,
+DocForge performs a bounded lexical focus search and refuses a tied best match instead of silently
+choosing one.
+
+The returned version-1 capsule includes:
+
+- The exact project, adapter, source generation, effective policy, request, and retrieval-plan
+  hashes.
+- Ordered focus and related evidence with source paths, content hashes, graph paths, and all
+  qualifying relationship reasons observed during the bounded traversal.
+- Explicit evidence gaps and omissions, including whether a check completed.
+- Provenance limitations for facts that the current graph does not carry, such as extractor
+  identity, observation time, and source provenance for relationships.
+
+Project descriptors still own the valid relation vocabulary. The planner recognizes a fixed alias
+map for structure, implementation, dependency, execution, data, evidence, and context. Any other
+valid project relation is returned unchanged as `unclassified`; it is never assigned guessed task
+semantics.
+
+A relationship inside `relationship_path` describes the direction traveled from the preceding
+node. A relationship inside `relationship_reasons` describes direction from the evidence item
+itself. This keeps stored source and target identity exact while making each evidence explanation
+locally readable.
+
+Task context never exceeds 1,000 evidence items, 100,000 examined candidate edges, or 10,000 task
+query characters, even when a project configures broader general limits. An edge-work or
+unclassified-relation ceiling appears as an explicit omission rather than an unbounded response.
+
 Recommended release-candidate sequence:
 
 1. Call `docforge_bootstrap`. It synchronizes derived state and reports the exact fixed binding.
@@ -675,6 +706,11 @@ inspection pages may use hash summaries. A large diff may return `result_mode =
 "canonical_json_chunk"`; concatenate the chunks in order and verify `payload_hash` before decoding
 the reconstructed `operations` and `changes` object.
 
+`docforge_get_task_context` uses the same opaque continuation discipline over capsule evidence
+followed by capsule omissions. Keep the semantic task arguments unchanged while paging. Page size
+may change. Every page retains the same plan, collection, and capsule hashes. A `stale_cursor`
+means that the generation, policy, plan, or collection changed; discard earlier pages and restart.
+
 Canonical application records its terminal receipt immediately after the project-owned serializer
 verifies the new canonical state. A later index or render refresh failure is reported as degraded
 derived state with remediation, not as permission to apply the same canonical change again.