Establish Milestone 0 compatibility and quality gates

docs/COMPATIBILITY.md

@@ -0,0 +1,159 @@
+# DocForge2 Milestone 0 compatibility contract
+
+Milestone 0 establishes DocForge2 as the successor repository without renaming or replacing the
+working DocForge interfaces. Compatibility changes require an explicit decision, a contract-test
+update, and migration guidance.
+
+The compatibility gate is:
+
+```bash
+make contract
+```
+
+The complete repository gate is:
+
+```bash
+make gate
+```
+
+## Distribution and Python imports
+
+The Python distribution and import package remain `docforge`.
+
+The installed executable names remain:
+
+- `docforge`
+- `docforge-mcp`
+- `docforge-viewer-manager`
+
+The top-level imports recorded by `docforge.__all__` remain supported. The documented adapter,
+model, index, rendering, application, and MCP factory names imported from these submodules also
+remain supported:
+
+- `docforge.adapter_contract`
+- `docforge.application`
+- `docforge.index`
+- `docforge.mcp_server`
+- `docforge.models`
+- `docforge.render_contract`
+
+Names beginning with an underscore are implementation details. New public names may be added
+without breaking this contract.
+
+## CLI and MCP surfaces
+
+Existing `docforge` command names and arguments remain supported. Existing `docforge-mcp` tool
+names and arguments remain supported. Additive commands, tools, and response fields are allowed.
+Removing or changing an existing name, required argument, stable error code, or safety boundary
+requires an explicit compatibility decision.
+
+MCP results retain:
+
+- A structured `status`.
+- Project and source identity when available.
+- Stable structured domain errors.
+- A bounded content warning.
+- Staleness information.
+- The configured output-size limit.
+
+The result schema describes the common envelope. Operation-specific fields are additive and remain
+bounded by the configured tool-output limit.
+
+## Versioned data contracts
+
+Milestone 0 preserves:
+
+- Project descriptor schema version 1.
+- Node schema version 1.
+- Edge schema version 1.
+- Changeset schema version 1.
+- Result-envelope schema version 1.
+- SQLite index schema version 2.
+- Index-attestation schema version 1.
+- Incremental extraction-cache schema version 1.
+
+Indexes, attestations, extraction caches, previews, and rendered artifacts are disposable. A schema
+change may rebuild them. Canonical project content and stored proposals may not be silently
+rewritten to satisfy a new implementation.
+
+## Adapter compatibility
+
+An adapter implementing only:
+
+```python
+load_projection()
+```
+
+remains first-class. Incremental manifests, source extraction, deterministic assembly, Logic
+projection, and proposal or application support are optional capabilities. Incremental adapters
+must retain `load_projection()` as their independent clean-build and equivalence oracle.
+
+Project adapters remain explicitly composed. Generic DocForge does not discover arbitrary adapter
+modules or choose a project globally.
+
+## Preserved no-AST binding
+
+`docforge-mcp --project-root /project --no-ast` is a stable shorthand for the
+`preserve-no-ast` binding policy.
+
+The binding:
+
+- Keeps one-method complete-projection adapters working.
+- Keeps non-AST incremental fingerprinting and caching working.
+- Rejects nonempty function-Logic publication.
+- Rejects a pre-existing index containing function Logic.
+- Blocks `docforge_get_logic`.
+- Prevents the live viewer from pinning an index containing Logic.
+- Applies the same restriction during hash-bound canonical-application refresh.
+- Reports the effective policy through bootstrap and contract results.
+
+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
+write access from changing adapter code.
+
+## Changesets and application
+
+The following guarantees remain stable:
+
+1. Registration writes one complete proposal atomically.
+2. Proposal identity includes its project, root, base revision, canonical source hash, writer, and
+   ordered operations.
+3. Validation and diff inspection precede application.
+4. Append, rebase, abandonment, and application use exact current hashes.
+5. Stale, conflicting, unauthorized, unsafe, or invalid proposals fail closed.
+6. Canonical application is absent unless one startup-bound applier is configured.
+7. Derived refresh failures produce an explicit degraded receipt after canonical application. They
+   do not make an applied proposal safe to apply twice.
+
+## Rendering and visualization
+
+The `generic_html` renderer remains the supported version-1 manual projection. It retains confined
+paths, raw-HTML suppression, fixed template tokens, deterministic identities, atomic replacement,
+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.
+
+`ManualRenderPlan`, `GraphViewPlan`, a portable graph renderer, and independently packaged
+renderers are later-milestone direction. Milestone 0 does not claim that those contracts exist.
+
+## Safety boundary
+
+DocForge remains bound to one explicit project root. It rejects absolute paths, root escapes, and
+symbolic-link escapes. Documentation text remains untrusted data. Normal MCP operation exposes no
+arbitrary filesystem access, renderer execution, shell command, Git mutation, deployment,
+publication, or project switching.
+
+## Recorded weaknesses, not compatibility promises
+
+Milestone 0 records rather than redesigns these areas:
+
+- Generic warm reads still repeat whole-project discovery, parsing, and validation.
+- Tree-sitter and the JavaScript and C++ grammars remain mandatory installation dependencies even
+  when their runtime modules are unused.
+- Several version strings and defaults remain duplicated.
+- Large changeset results and context responses need compact receipt or pagination contracts.
+- Manual planning is not separated from rendering.
+- There is no portable graph-planning or graph-rendering contract.
+- DocForge2 does not self-host its bootstrap documentation.