Close Milestone 4 with adapter adoption evidence

docs/MIGRATING_FROM_V1.md

@@ -0,0 +1,79 @@
+# Migrating from DocForge v1
+
+DocForge2 preserves the `docforge` distribution, Python package, CLI command, MCP tool prefix,
+generic project descriptor version, and legacy adapter entry point. Migration is an additive
+validation exercise, not a canonical-content rewrite.
+
+Read [compatibility](COMPATIBILITY.md), [legacy and no-AST operation](LEGACY_AND_NO_AST.md), and
+[recovery](RECOVERY_AND_PERFORMANCE.md) before changing a production binding.
+
+## What remains compatible
+
+- Generic Markdown and TOML projects keep `.docforge/project.toml` schema version 1.
+- A custom adapter implementing only `load_projection()` remains valid.
+- Existing canonical nodes, stable IDs, source paths, relationship vocabulary, changesets, and
+  reviewed hashes are not silently rewritten.
+- Existing CLI and MCP names remain available. New fields, commands, tools, plans, policies, and
+  reference integrations are additive.
+- `docforge-mcp --no-ast` remains the shorthand for the preserved no-AST binding.
+
+Disposable index and cache schemas may change. Rebuild them rather than copying them as authority.
+
+## Recommended migration
+
+1. Record the v1 package version, adapter identity, project descriptor, canonical source hash,
+   active changesets, generated client configuration, and current rendered outputs.
+2. Back up canonical sources and active proposal files. Derived `.docforge/cache`, preview,
+   portable-graph, and viewer state need not be authoritative backups.
+3. Install the DocForge2 candidate in a separate environment. Do not repoint the production MCP
+   binding yet.
+4. Run the existing adapter through complete loading and `ProjectIndex.check()`. For incremental
+   adapters, verify complete/incremental equivalence. Logic-producing incremental adapters must
+   implement the independent complete assembly oracle.
+5. Compare project ID, adapter, revision, source hash, primary node and edge hashes, Logic policy,
+   and retrieval results with the v1 evidence.
+6. Recompose effective capability and projection policy. Do not assume that a new default grants
+   proposal, application, rendering, or viewer access.
+7. Rebuild disposable indexes, extraction caches, fragments, receipts, previews, and portable
+   artifacts from the validated candidate.
+8. Generate a new client fragment. Generic projects use `docforge configure`; custom adapters use
+   `AdapterLauncherV1` with `generate_adapter_client_configuration()`.
+9. Run doctor, real MCP bootstrap, representative retrieval, rendering status, recovery, and
+   exact-hash proposal/application checks in a disposable or shadow environment.
+10. Repoint one production binding only after the candidate and rollback procedure pass.
+
+## Adopting reference adapters
+
+The repository reference adapters are narrow syntax evidence, not automatic semantic replacements
+for mature v1 integrations. Python publishes modules, classes, functions, and local imports.
+JavaScript and TypeScript publish syntax plus static project-relative imports and re-exports.
+C++ uses a confined `compile_commands.json` as inert translation-unit inventory and publishes
+directly resolvable project-local quoted includes.
+
+Do not replace a compiler-, language-server-, or project-owned semantic adapter if the task depends
+on resolved calls, types, inheritance, macros, compiler include semantics, runtime facts, or
+ownership. Use [reference adapters](REFERENCE_ADAPTERS.md) as a measured starting point.
+
+## Changesets
+
+Existing changesets remain bound to their original project, root, base revision, source hash,
+writer, operations, and exact hash. Do not edit a changeset to make it look current. Retrieve and
+validate it through the candidate. Rebase only when every precondition remains true; otherwise
+create and review a new proposal.
+
+Before enabling canonical application, prove the exact serializer round trip and recovery behavior
+for the selected adapter. The fixed reference MCP server is intentionally read-only.
+
+## Rollback
+
+Keep the v1 environment, configuration fragment, and service definition until the DocForge2
+binding has passed live validation. To roll back:
+
+1. Stop the DocForge2 MCP/viewer processes.
+2. Restore the previous client or service binding.
+3. Restore canonical sources only if a verified application receipt says they changed and the
+   adapter-specific rollback requires it.
+4. Discard DocForge2-derived indexes, receipts, fragments, previews, and portable artifacts.
+5. Restart v1 and verify its recorded project/source identity.
+
+Never move a published tag or reuse a version identity for a corrected release.