DocForge2/docs/MIGRATING_FROM_V1.md

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, legacy and no-AST operation, and recovery 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.

Maintained v1.0.0 migration evidence

make migration-m5 archives and executes the actual annotated v1.0.0 release, then opens its fixture, index, and active proposal through DocForge 1.4.0. The frozen tag object is 2d7d306a37da89f1c860c7f0be161c45386acf61; it identifies commit 593c173b453236a6872d0a4e88e7a51a67a21cde.

The tagged release contains an inherited identity mismatch that the migration proof records rather than hiding: distribution metadata says 1.0.0, while docforge.__version__ and the MCP server report 0.15.0. DocForge 1.4.0 replaces that duplicated state with one authoritative version and requires its package and server values to agree.

The maintained fixture evidence is exact:

• Canonical collection hash: 9fde91b6b08669177d690cdf9f91b162120baee1f7e24b05fec67f56617f286a.
• Graph snapshot hash: 45bef8b0e1a4dac976e096dcf8f9048e1268211cd7f7638cdf99951428ec0500.
• Source hash: 0aa6ad13a95355102300a69b2f9d06883c301d63e2624b083e45f15102dab504.
• Active proposal hash: 2c055dfae45443b4a4d9d4087ef70959e7293beae8d27acb14ffffe52eca7111.
• Proposal-file hash: 4658d494b43bd7c6cc3e3f5933a2c878c817b52bc4566e9e8429e7b8e43ca007.

Current loading preserves all five identities and every canonical byte. It rebuilds the disposable index from schema 1 to schema 3 without changing the graph or active proposal. All 20 tagged CLI commands remain in the current 28-command surface, and all 25 tagged MCP tools remain in the current 36-tool application-enabled surface. These counts describe the maintained rehearsal, not a promise that every additive current command belongs in a legacy binding.

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 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.