DocForge2/docs/COMPATIBILITY.md

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:

make contract

The complete repository gate is:

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.policy
• 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 3. Version 2 indexes remain disposable and automatically rebuild; 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 when pagination is not requested.

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:

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.

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 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.
• One individually oversized context entry is represented as explicit bounded omission evidence; callers use targeted retrieval for that node.
• One individually oversized changeset diff is transported as reconstructable canonical-JSON chunks. Cursors are corruption-detecting read tokens, not authenticated authorization tokens.
• 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.