feat: add isolated proposal changesets

docs/CONTRACT.md

@@ -1,12 +1,12 @@
-# DocForge 0.1 contract
+# DocForge 0.2 contract
 
 ## Authority boundary
 
 DocForge is bound to one explicit project root. Canonical project files own documentation facts.
 Indexes, query results, context packs, changesets, previews, and renders are derived artifacts.
 
-The generic core may validate and retrieve canonical nodes. A future proposal service may write only
-isolated changesets. Canonical application, project builds, Git mutation, deployment, and
+The generic core validates and retrieves canonical nodes. A project-bound proposal service writes
+only isolated changesets. Canonical application, project builds, Git mutation, deployment, and
 publication remain external integration actions. Passive revision detection may read the current Git
 commit when Git is available; it cannot change repository state.
 
@@ -16,9 +16,9 @@ commit when Git is available; it cannot change repository state.
 - Node schema: `schemas/node.schema.json`, version 1.
 - Edge schema: `schemas/edge.schema.json`, version 1.
 - Result envelope: `schemas/result.schema.json`, version 1.
-- Changeset schema: `schemas/changeset.schema.json`, version 1, reserved for DFG-3.
+- Changeset schema: `schemas/changeset.schema.json`, version 1.
 - Index schema: version 1, disposable and reproducible.
-- Core and CLI: version 0.1.0.
+- Core, CLI, and MCP server: version 0.2.0.
 
 Schema files describe the generic interchange contract. Runtime validation remains responsible for
 path confinement, source hashing, relationship resolution, dependency cycles, project limits, stale
@@ -40,10 +40,23 @@ Successful operations identify the project, adapter, current revision when avail
 source hash. Errors use a stable code, direct message, and structured details. Query operations fail
 if canonical source no longer matches the derived index.
 
-## Write model reserved for DFG-3
+## Isolated proposal model
 
 Create, update, move, and delete are ordered node operations inside an isolated changeset. Every
 operation names its expected base hash. A move preserves the stable node ID. A delete must resolve
-required incoming relationships. Validation and application are atomic; prose is never auto-merged.
+every incident relationship. Proposal validation and storage are atomic. Canonical application
+remains external, and prose is never auto-merged.
 
-Normal MCP access will not expose canonical application or arbitrary file writes.
+The MCP process binds to one configured writer identity at startup. The project descriptor grants
+that writer explicit families and operation types. A changeset records its creator, project root
+fingerprint, base revision, canonical source hash, and ordered operations. Every append requires the
+current changeset hash, so simultaneous writers cannot silently lose an operation.
+
+Changesets from the same canonical base may coexist only when their touched node and source sets do
+not overlap. Exact overlaps return structured conflicts naming the other changesets, nodes, and
+sources. A stale canonical base, stale node hash, stale changeset hash, unauthorized family, unsafe
+path, invalid graph, dependency cycle, unresolved delete relationship, or configured limit fails
+before the proposal file changes.
+
+Normal MCP access does not expose canonical application, arbitrary file writes, previews, renderer
+execution, shell commands, Git mutation, build commands, deployment, or publication.

docs/MCP_CONTRACT.md

@@ -1,7 +1,8 @@
 # MCP boundary
 
-The DFG-2 server will use local standard input/output transport and bind once to the explicit
-`--project-root` supplied at process startup. It will not expose an HTTP port in the first release.
+The server uses local standard input/output transport and binds once to the explicit
+`--project-root` supplied at process startup. Optional proposal access also binds once to the
+configured `--proposal-writer`. It does not expose an HTTP port in the first release.
 
 ## Read tools
 
@@ -20,24 +21,27 @@ The DFG-2 server will use local standard input/output transport and bind once to
 Each response states that document text is project content, not higher-priority instructions. Each
 response includes project identity, revision, source hash, adapter version, and staleness state.
 
-## Proposal tools reserved for DFG-3
+## Isolated proposal tools
 
 - `docforge_create_changeset`
+- `docforge_list_changesets`
+- `docforge_get_changeset`
 - `docforge_propose_node_create`
 - `docforge_propose_node_update`
 - `docforge_propose_node_move`
 - `docforge_propose_node_delete`
 - `docforge_validate_changeset`
 - `docforge_get_changeset_diff`
-- `docforge_preview_changeset`
 
-Proposal tools may write only below the configured changeset root. They never change canonical files.
+Proposal tools may write only below the configured changeset root. They never change canonical
+files. Without `--proposal-writer`, mutation tools return `proposal_access_disabled`. Validation and
+diff retrieval remain available for existing changesets.
 
 ## Excluded tools
 
 The normal server never exposes shell execution, arbitrary reads or writes, canonical changeset
-application, Git mutation, project builds, deployment, publication, global project selection, or
-cross-project retrieval.
+application, preview generation, renderer execution, Git mutation, project builds, deployment,
+publication, global project selection, or cross-project retrieval.
 
 DocForge pins the official stable Python MCP SDK to the compatible `mcp>=1.28,<2` release line.
 Migration to a later major release requires a separate contract and protocol compatibility review.