--- title: Upgrading from 1.x to 2.0 description: Migration steps for the 2.0 breaking release. Schema versions stay 1 and Layer 0 stays deterministic. owner: maintainers lifecycle: active sourceOfTruth: docs/migration/1.x-to-2.0.md validationPath: pnpm typecheck && pnpm test --- # Upgrading from 1.x to 2.0 Inventory and migration steps for the breaking release. Index and handoff schema versions remain 1. Layer 0 remains deterministic. No study baseline or study hash is migrated. | Surface | 1.x behavior | Why change or retain | Replacement and migration | Risk | | --- | --- | --- | --- | --- | | CLI `fix propose links` / `normalize` | Produces whole-file `FixProposalV1` | Replace whole-file mutation binding with region evidence | Submit region edits as `RemediationV1`; regenerate proposals and human approvals | Old proposal JSON cannot be applied | | CLI `fix approve` / `apply` | Approves by a supplied name and applies whole files | A name alone cannot prove authenticated authority | Local human confirms explicitly; --by records attribution only; fresh evidence and configured gates run through the region library | MCP and the Action cannot approve/apply | | MCP `docbridge.proposals` whole-file actions | `propose-links`, `propose-normalize`, `approve`, `apply` use whole files | Match region contract without introducing another mutation engine | Use propose/revalidate with base snapshot and allowedRoots; human CLI handles approve/apply and DecisionV1 rejection | Existing consumers need a coordinated migration | | Public `FixProposalV1`, schema and proposal helpers | Whole-file library contracts exported | Retain for migration callers until their consumers can move; CLI/MCP must stop using them | Move to `RemediationV1`, `DecisionV1`, `createRemediation`, `revalidateRemediation`, `approveRemediation`, `applyRemediation`, `recordDecision` | Removing exports prematurely breaks callers | | Legacy index / snapshot / retrieval `sha256-normalized-v1` | Original verifier accepts legacy identity; index gate can pass | Legacy artifacts must be migration guidance only | Regenerate with `ak-docs index`; recreate snapshots and dependent projections using semantic identity | Hashes cannot be compared across algorithms; approvals never transfer | | Study, benchmark, storage and exact approval normalized hashes | Independent versioned contracts use normalized hashing | Retain: ADR 0010 explicitly preserves study hashes; these are not legacy index identity | No migration; distinguish artifact kind before interpreting algorithm name | Global string replacement corrupts unrelated contracts | | `index.contentHash` config | Accepts only normalized algorithm even though new index emission is semantic | Align declared configuration with semantic index identity | Configure `sha256-semantic-v1`; legacy setting is rejected with migration guidance | Effective configuration hash changes | | Memory `ingestDir` and adapter defaults | Configurable playbook directories; rule adapter always reads its fixed default | Configuration must control every selected adapter; preserve configurable notes and entity links | Keep `ingestDir`, use `rulesDir` for configurable rule directories, centralize documented defaults | Unexpected memory files must not be ingested when explicit paths are supplied | | Public `ingestAgentMemory` / `ingestCursorRules` | Convenience helpers select fixed paths | Keep callers working with documented defaults and explicit path arguments | Supply configured directories; prefer `ingestMemoryCandidates` | Existing default behavior remains intentional | | Ecosystem `properties` shim | Deprecated projection of canonical `products` | Retain: pinned upstream artifact and shared consumers still require compatibility | Consumers migrate to `products`; remove only after upstream contract migrates | Local removal violates immutable upstream verification | | CLI flags / commands / aliases | No active CLI flag or alias is marked deprecated in source or CLI spec | Retain supported commands and short help/version flags | No speculative removals | Removing unmarked surfaces would exceed the requested deprecated cleanup | | Config adapters `session-export` / `bootstrap-delta` | Reserved adapters are accepted with a warning and ignored | Reject unsupported adapters during configuration validation and direct ingestion | Remove these entries; use `playbook-memory` or `cursor-rules` | Previously accepted reserved configurations now fail | | MCP legacy Content-Length transport | Accepted alongside newline JSON | Retain: consumer compatibility, no announced removal | New integrations use newline JSON | Removing framing silently breaks old clients | | Action / plugins / MCPB | Invoke current binary and advertise current tool surface | Keep names and schema-compatible handoffs; update descriptions for region migration | Upgrade package together with clients; use migration guide | No unattended human approval authority is introduced | No deprecated public type/export annotation was found beyond the whole-file fix migration surface. Legacy discovery evidence, aliases, service-denied local APIs, and strict handoff emission are compatibility behavior, not deprecation notices. ## Migration steps 1. Upgrade every reader before regenerating indexes. Keep index/handoff schema versions at 1; unknown consumers still receive legacy handoff fields. 2. Replace `index.contentHash: sha256-normalized-v1` with `sha256-semantic-v1`, then run `ak-docs index`. Regenerate snapshots with `ak-docs discover` and reports with `ak-docs reconcile`. Legacy index emission is refused, including injected-storage publication. Read-only legacy projections remain available for migration verification. Original index drift is diagnosed before replacement; study and benchmark baselines remain unchanged. 3. Regenerate whole-file proposals as RemediationV1 through the region library or a compatible producer. Old FixProposalV1 approvals cannot transfer. CLI propose/revalidate requires the remediation JSON, `--base` snapshot and explicit `--allowed-root` values. MCP uses `action: propose|revalidate`, `proposal`, `base`, and `allowedRoots`. 4. Confirm CLI approve/apply/reject interactively with `--by`, or explicitly assert local authority with `--yes`. Attribution is not authentication. MCP cannot approve/apply; the Action refuses these actions even with `--yes`. Authenticated hosts retain the trusted callback library interface. 5. Fresh findings are recomputed from the base and current discovery, including routed-to-L2 findings. Missing, changed, excluded or rejected evidence fails closed. Every changed review binding requires renewed human approval. 6. Remove reserved `session-export` and `bootstrap-delta` memory adapters. In 1.x they were accepted with a warning; in 2.0 they are validation errors. 7. Configure `intelligence.memory.ingestDir` and `rulesDir` independently. Each accepts one directory or an ordered list; defaults are `.agent-memory` and `.cursor/rules`. Explicit paths replace defaults. Existing note/entity links are preserved; outside-repository paths are rejected. Application executes all configured gates against written files. Failure restores originals. No index mutation or gate bypass happens implicitly, so an index-freshness failure rolls back application. A host that manages fresh index evidence should use the existing library verification callback. Rejection requires a valid enrichment overlay and a DecisionV1 file (`fix reject --decision `); finding rejection suppresses unchanged evidence, while remediation rejection rejects only that correction.