Add versioned effective policy

docs/COMPATIBILITY.md

@@ -35,6 +35,7 @@ remain supported:
 - `docforge.index`
 - `docforge.mcp_server`
 - `docforge.models`
+- `docforge.policy`
 - `docforge.render_contract`
 
 Names beginning with an underscore are implementation details. New public names may be added
@@ -72,6 +73,8 @@ Milestone 0 preserves:
   version 3 adds a source-ordered incoming-edge index for bounded impact traversal.
 - Index-attestation schema version 1.
 - Incremental extraction-cache schema version 1.
+- Effective process-policy schema version 1. The project descriptor remains schema version 1;
+  machine-specific capability selection is a startup binding, not canonical project content.
 - Read-pagination schema version 1. Existing tool names and required arguments are unchanged.
   Context and changeset MCP reads accept optional limits and opaque generation-bound cursors.
   Direct Python changeset methods and the ordinary CLI context command retain full legacy results
@@ -112,6 +115,10 @@ The binding:
 - Applies the same restriction during hash-bound canonical-application refresh.
 - Reports the effective policy through bootstrap and contract results.
 
+The legacy `adapter_policy` payload and error codes remain unchanged. The version-1
+`effective_policy` is additive and makes precedence, capability mode, render behavior, blocked
+tools, and prohibitions machine-readable.
+
 DocForge does not inspect arbitrary adapter source to prove which parser implementation it uses.
 The no-AST binding is an owner-selected process policy backed by Logic publication and retrieval
 enforcement. It is not a filesystem sandbox and cannot stop an unrelated process with repository

docs/MCP_CONTRACT.md

@@ -16,6 +16,18 @@ Canonical application is a second independent startup gate. The generic server a
 `--canonical-applier WRITER_ID`. A project adapter must also supply a compatible project-owned
 canonical applier implementation.
 
+The additive `--capability-mode read|proposal|application|operator` option selects a versioned
+effective process policy. Existing factory defaults and tool ordering remain unchanged: the
+read-only factory exposes the read surface, the ordinary project factory exposes the proposal
+surface, and an application-enabled factory adds exact-hash application. `application` mode fails
+closed unless a canonical applier is bound. `operator` is reserved for explicitly selected
+operator-only tools and adds none in the current contract.
+
+Bootstrap and contract results include `effective_policy` schema version 1 plus a separate
+`capabilities` record. Policy states the requested process behavior. Capabilities state the actual
+registered surface and startup-bound proposal/application access. The project descriptor remains
+schema version 1 and does not silently acquire machine-specific process policy.
+
 ## Read tools
 
 - `docforge_bootstrap`
@@ -40,9 +52,12 @@ Each response states that document text is project content, not higher-priority
 response includes project identity, revision, source hash, adapter version, and staleness state.
 Every normal tool call first checks current source identity and atomically rebuilds disposable index
 state when it is missing, stale, or invalid. `docforge_bootstrap` performs that synchronization and
-returns the complete fixed binding, active index path, proposal and application capabilities, and
-recommended workflow. `docforge_sync` exposes the same idempotent synchronization explicitly.
-Neither operation changes canonical sources.
+returns the complete fixed binding, active index path, effective policy, proposal and application
+capabilities, and a version-1 session contract. Bootstrap reuses the identity proven by
+synchronization instead of loading the project again. Its first operation and workflow guidance
+mention proposal or application tools only when the corresponding startup access is enabled.
+`docforge_sync` exposes the same idempotent synchronization explicitly. Neither operation changes
+canonical sources.
 
 Search, filter, backlinks, dependencies, and impact accept explicit result limits bounded by the
 project `max_results` policy. Omitted limits are still capped. Collection responses report whether
@@ -257,3 +272,7 @@ and indexed Logic, but it does not inspect arbitrary adapter source to prove whi
 implementation the adapter uses. DocForge still exposes no filesystem sandbox and cannot prevent
 an unrelated process with direct repository write access from editing adapter files. Repository
 permissions and project instructions remain responsible for that broader boundary.
+
+The legacy `adapter_policy` object remains byte-compatible. It is now a projection of the
+versioned `effective_policy`; `--no-ast` restrictively overrides adapter evolution, AST analysis,
+and Logic indexing without widening any other capability.

docs/USER_MANUAL.md

@@ -513,6 +513,19 @@ docforge-mcp \
 
 Omit `--proposal-writer` when the MCP client should not create or append proposals.
 
+Select the session's declared surface explicitly when useful:
+
+```bash
+docforge-mcp \
+  --project-root /absolute/path/MyProject \
+  --capability-mode read
+```
+
+Supported modes are `read`, `proposal`, `application`, and `operator`. Existing startup defaults
+remain compatible. Capability mode describes the registered surface; bootstrap separately reports
+whether a configured writer or applier actually grants mutation access. Application mode refuses
+startup without a canonical applier. Operator mode is reserved and currently adds no tools.
+
 Add `--diagnostics` when profiling a development or benchmark session. Each MCP response then
 includes bounded stage timings and compiler-work counters. The same flag is available on
 `docforge`. Diagnostics are disabled by default, record no project content or paths, and never
@@ -530,6 +543,11 @@ docforge-mcp \
 Without `--canonical-applier`, `docforge_apply_changeset` is not registered. The flag is an
 identity, not a command. The changeset creator, configured writer, and canonical applier must agree.
 
+Call `docforge_bootstrap` first. Its version-1 `session_contract` contains the fixed binding,
+current graph generation, effective policy, actual capabilities, render policies, prohibitions,
+and a recommended first operation. Workflow guidance does not recommend registration or
+application when those startup capabilities are unavailable.
+
 Example MCP client configuration:
 
 ```json