SDD Docs

[tmshort]

Summary

Adds the Specification-Driven Design (SDD) documents for the OLMv0→OLMv1 migration feature
(OCPSTRAT-2693).

These four documents form the design contract for the migration library implemented in PR #2.
They are committed first so reviewers can evaluate the design independently of the implementation.

---

Documents

File	Purpose
migration/README.md	Feature overview — the two CLIs, operator states, high-level flow, and architecture
migration/REQUIREMENTS.md	Functional and architectural requirements (R1–R10); every Subscription, OperatorGroup, and CatalogSource field; ClusterExtension target mapping
migration/PLAN.md	Eight implementation phases with exit criteria, dependencies, and Jira story references (OPRUN-4717 through OPRUN-4723)
migration/VALIDATION.md	Verifiable acceptance criteria (V1–V7) and a requirement-traceability table linking every R-item to at least one validation check

Also includes:

• README.md — repo-level overview pointing to the migration documents
• .gitignore — ignores built binaries (bin/), test artifacts, editor files, and runtime backup directories

---

Design highlights

• Two CLIs — migrate-operators-v0-to-v1 (verb subcommands: check, convert, rollback, cleanup) and migrate-catalogs-v0-to-v1
• Four-state classification — Eligible / Ineligible / AlreadyMigrated / Conflict
• Non-interactive — --dry-run for preview; all overrides via explicit --acknowledge-* flags
• Close-to-zero downtime — orphan cascade on Subscription/CSV deletion; workloads keep running
• SecretPacker — Secret-backed COS objects to handle large bundles within etcd limits
• Full field-by-field mapping — every Subscription, OperatorGroup, and CatalogSource field is specified with its exact OLMv1 target

Related

• Implementation: PR Implement OLMv0→OLMv1 migration library and CLIs (Phases 1–5, 7) #2
• Upstream prototype: perdasilva/operator-controller migration
• APIService renderer support: operator-controller PR #2885

[perdasilva]

lgtm

[joelanford]

What do you think about a better structure for SDD docs? For example:
specs/<dateYYYYMMDD>-<featureSlug>/README.md.

That way there is a natural location in the repo for all specs, and they are time-ordered.

Also, nit: lowercase the names of the other files so that the README is the most prominent?

[tmshort]

Any objection to doing it as a follow-on?

[joelanford]

WDYT about adding the actual SDD skills to this repo so that future contributors can easily follow the same style and workflows.

For example, https://github.com/joelanford/library-olm/tree/main/.claude/commands, maybe starting with:

• ideate / quick-item
• plan-next-phase (maybe rename to refine?)

Also, specs/conventions.md, specs/mission.md, and specs/tech-stack.md are useful context that we should commit as well. I have those for my library-olm repo here: https://github.com/joelanford/library-olm/tree/main/specs

[tmshort]

WDYT about adding the actual SDD skills to this repo so that future contributors can easily follow the same style and workflows.

Can that be done as a separate PR? These are specific for the migration tool. That seems more general purpose.

[joelanford]

Maybe also squash this down to a single commit?

[tmshort]

Maybe also squash this down to a single commit?

But the history! ;)