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

## 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 2.0.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 2.0.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](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.