jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/openspec/specs/incremental-migration/spec.md

2.3 KiB
Raw Permalink Blame History

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