54 lines
2.3 KiB
Markdown
54 lines
2.3 KiB
Markdown
# Spec: Incremental Migration
|
||
|
||
## Purpose
|
||
|
||
Defines the ordering constraints for onboarding the memory system into production: the system must be built and validated before any migration is performed, projects are onboarded one at a time, and bulk vault migration is deferred to last.
|
||
|
||
## Requirements
|
||
|
||
### Requirement: System is validated before bulk migration
|
||
|
||
The build SHALL be completed and validated end-to-end against a small fixture set and one small project containing both code and documents before any bulk vault migration is performed.
|
||
|
||
#### Scenario: Fixtures feed the gate without bulk migration
|
||
|
||
- **WHEN** the Step 2c benchmark gate is run
|
||
- **THEN** it uses a 5–10 note fixture set
|
||
- **AND** the remaining vault notes are not migrated at that point
|
||
|
||
#### Scenario: First end-to-end validation is a mixed project
|
||
|
||
- **WHEN** the system is first validated end-to-end
|
||
- **THEN** the target is one small project containing both code and documents
|
||
- **AND** validation covers both the document extraction path and the code (tree-sitter) path
|
||
|
||
### Requirement: Projects are onboarded one at a time
|
||
|
||
After the system is validated, projects SHALL be onboarded individually, with observation and adjustment between each, rather than migrated in bulk.
|
||
|
||
#### Scenario: One project at a time
|
||
|
||
- **WHEN** a project is onboarded after initial validation
|
||
- **THEN** it is migrated on its own
|
||
- **AND** its migration is observed and the process adjusted before the next project is onboarded
|
||
|
||
### Requirement: Bulk vault migration is deferred to last
|
||
|
||
Bulk migration of the full vault SHALL be deferred until after the system is built and validated, rather than performed as the first build step.
|
||
|
||
#### Scenario: Bulk migration ordering
|
||
|
||
- **WHEN** the build order is followed
|
||
- **THEN** bulk vault migration occurs after system validation
|
||
- **AND** only the fixture notes are migrated beforehand
|
||
|
||
### Requirement: Build-order inversion is recorded in an ADR
|
||
|
||
The inversion of the documented build order (from vault-migration-first to build-first / migrate-incrementally) SHALL be recorded in a new ADR and reflected in the project's locked-decisions pointer.
|
||
|
||
#### Scenario: ADR captures the inversion
|
||
|
||
- **WHEN** the build order is resequenced
|
||
- **THEN** a new ADR (ADR-013) records the inversion and its rationale
|
||
- **AND** the "Decisions locked" pointer in `CLAUDE.md` is updated to reference it
|