Close Milestone 4 with adapter adoption evidence

docs/LEGACY_AND_NO_AST.md

@@ -0,0 +1,80 @@
+# Legacy adapters and no-AST policy
+
+DocForge preserves the original one-method adapter contract while offering incremental extraction,
+complete graph-plus-Logic assemblies, and an independently selectable no-AST MCP policy. These are
+separate compatibility boundaries.
+
+## One-method adapters remain valid
+
+An existing adapter that implements only:
+
+```python
+def load_projection(self) -> AdapterProjection: ...
+```
+
+continues to work. It receives the same projection validation, indexing, querying, visualization,
+and MCP behavior as before. It does not receive extraction-cache speedups and publishes no Logic
+through the complete assembly contract.
+
+Incremental adoption is additive. Implement `load_manifest()` and `extract_source()` while keeping
+`load_projection()` as the independent complete graph oracle. If incremental contributions publish
+Logic, also implement `load_complete_assembly()` so complete and incremental graph-plus-Logic
+output can be compared exactly. The public authoring surface is `docforge.adapter_sdk`; see the
+[Language Adapter Authoring Guide](ADAPTER_AUTHORING_GUIDE.md).
+
+## What no-AST means
+
+`--no-ast` is an immutable policy on one MCP process binding. It preserves the configured adapter
+strategy but forbids AST, Tree-sitter, compiler-AST, and function-Logic evolution for that binding.
+It also rejects nonempty Logic before index publication and rejects a pre-existing index that
+contains Logic before reads or live visualization.
+
+Start the generic server with:
+
+```bash
+docforge-mcp --project-root /absolute/path/to/project --no-ast
+```
+
+Project-owned integrations select the same policy with
+`create_project_server(..., no_ast=True)` or `create_read_only_server(..., no_ast=True)`.
+`docforge_bootstrap` and `docforge_get_contract` report the effective policy, and
+`docforge_get_logic` returns `adapter_policy_forbids_logic`.
+
+Changing this policy requires a new process. It does not rewrite or reload an adapter in place.
+
+## What no-AST does not mean
+
+No-AST is not:
+
+- an inspection mechanism that proves which parser an arbitrary adapter uses;
+- a filesystem, Python-import, or process sandbox;
+- a promise that the adapter performs no non-AST fingerprinting, dependency discovery, caching, or
+  complete-projection loading; or
+- permission to change project files, adapter code, or the configured capability surface.
+
+Repository permissions and project instructions remain responsible for processes that have direct
+filesystem access. The MCP boundary still excludes shell execution, arbitrary file operations,
+Git mutation, builds, deployment, publication, project switching, and cross-project retrieval.
+
+## Reference adapters are not no-AST adapters
+
+The built-in Python reference extracts syntax and Logic with the standard-library AST. The
+JavaScript, TypeScript, and C++ references extract syntax and Logic with their optional
+Tree-sitter grammars. Their normal projections contain Logic, so they must not be presented or
+configured as no-AST adapters.
+
+The narrower performance statements in [Reference Adapters](REFERENCE_ADAPTERS.md) concern
+specific manifest and warm-cache paths. A parser-free manifest does not turn an adapter that
+publishes AST-derived Logic into a no-AST adapter.
+
+## Migration choices
+
+Keep a one-method adapter when its complete rebuild is acceptable and no function Logic is needed.
+Adopt incremental extraction when measured source parsing dominates synchronization. Adopt the
+complete assembly contract when Logic is published or overlapping raw evidence needs deterministic
+ownership.
+
+Choose no-AST only when the project binding must forbid AST-derived publication and future adapter
+upgrades of that kind. It is a binding policy, not a substitute for adapter confinement,
+conformance tests, restart detection, cache recovery, or the full proof matrix in
+[Incremental Adapter Indexing](INCREMENTAL_INDEXING.md).