blackroad-os-archive/docs/MIGRATION_PLAYBOOK.md

Migration Playbook

Use this checklist to migrate legacy or out-of-date repos into the modern BlackRoad OS constellation.

1. Catalog it

   • Add the repo entry to catalog/repos.yaml with status legacy or archived.
   • Include owner handles, tags, and any known domains.

2. Generate and fill a Cover Sheet

   • Run npm run generate:covers to create a skeleton if missing.
   • Complete the narrative, history, and why-it-matters sections in /covers/<repo>.cover.md.

3. Decide the path forward

   • Choose whether to merge into a core repo, split into packs, or deprecate.
   • Note the recommended action on the cover sheet (keep-live, snapshot, deprecate, or merge).

4. Link to the canonical destination

   • Update the cover sheet to reference modern equivalents (e.g., blackroad-os-core, blackroad-os-operator).
   • Set the GitHub repo status to archived if it will no longer receive updates.

5. Update infrastructure + docs

   • Ensure redirects or gateway rules are in place via blackroad-os-operator and blackroad-os-api-gateway.
   • Add cross-links in blackroad-os-docs or Prism Console so stakeholders can find the new home.

6. Snapshot (text-only) references

   • Document snapshot metadata in /snapshots/ if necessary (never store binaries here).

7. Validate

   • Run npm run validate to check schema compliance and ensure legacy items have cover sheets.