design: media-library - Design the import and reference-migration workflow #281

Design Summary

Define the TOA media import and reference-migration workflow. Drafting may proceed in parallel using provisional catalogue and storage assumptions; final workflow approval requires approved inputs.

Current status — 19 October 2026

In Progress. Design documents and recovery-support scripts exist. They do not establish an approved migration workflow, verified reference replacement, responsive build integration or tested rollback.

Linked Stories/Tasks/PRs/Design Files / Related Epics

Parent: #267. Catalogue: #279. Storage evaluation: #280. No implementation PR or workflow mockup specified.

Milestones & Timeline

Not set. Drafting may proceed in parallel using provisional catalogue and storage assumptions; final workflow approval requires approved inputs.

Design Details

Define deduplication, original/derivative handling, verified mappings between existing Figma references and library assets, rollback and protection of existing references until replacements are verified.

Designs / Mockups

Not applicable to visual UI design; the deliverable is an operational workflow specification. No mockups requested.

Accessibility Considerations

No additional accessibility work specified; do not invent visual-design requirements.

Acceptance Criteria

• Specify import sequencing, deduplication and original/derivative handling.
• Define verified reference mappings and pre-replacement checks.
• Define failure handling, rollback and explicit approval gates for protected references.
• Identify implementation inputs, unresolved decisions and required validation evidence.

Dependencies

Catalogue and storage decisions.

Testing/Validation Steps

Define verification before replacement, preserving existing references until mappings and replacements are verified.

Additional Context

This issue defines the workflow; it does not authorise asset uploads or reference replacement.

Definition of Ready (DoR)

• Design-only scope and protection safeguards are documented.
• Catalogue contract, storage/workflow decision and implementation handoff are agreed.

Definition of Done (DoD)

• Reviewer accepts the workflow, verification and rollback specification.
• Implementation receives evidence-linked inputs; design completion is not recorded as migration execution.

Immediate next steps

Reconcile the workflow with the catalogue contract and recovery findings. Specify deduplication, original preservation, derivatives, mappings, pre-replacement checks, failure handling, rollback and separate implementation gates.

Evidence required

Reviewed workflow with explicit inputs, outputs, safeguards, unresolved decisions and mapping/rollback acceptance criteria. This issue does not authorise uploads or protected-reference changes.

Specification references

Historical update correction — 19 October 2026: PR #297 closed without merging. Related specification material nevertheless entered develop through separate integration and successor work; this does not establish delivery approval.

• Specification
• Plan
• Tasks

Draft specification/planning references at revision 02aee367; not evidence of approval, completed recovery or implementation. Task correspondences below describe relevant scope, not exclusive ownership or completed work.

No dedicated task group delivers this issue’s acceptance criteria. T025 and T034 provide provenance/reference-check context only; import sequencing, deduplication, verified mappings, rollback and replacement approval remain coverage gaps.

✅ Update (2026-10-17): Specification consolidation complete (PR #296 + #297 merged). Current references available on develop branch:

• Specification
• All planning docs

Branch instructions

Planning guidance, not migration approval. Repository revision D: 4ecdb26d9655a48bf000a7c89da2f70383edce87; shared governance revision G: 8f28eca80bff198879f7aaf496717dc0551bb32e.

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this operational-workflow specification; counterpart GitHub issue 281. No visual UI deliverable or migration execution included.
• Parent context: retain existing coordination relationship only. Withhold parent identifiers/URLs from branch names, PR titles/bodies and prompts until effects are verified. Never use the parent as a native development or closing target.
• Allowed closing targets: none now. Eligibility requires the entire workflow outcome, accepted inputs, safeguards and reviewer acceptance, not merely a documentation merge.
• Branch state: proposed new branch, not created; no existing branch verified for reuse.
• Branch: docs/media-import-workflow.
• Classification: operational design documentation independently of the design label. docs/ fits specification/task changes; no UI or image-processing implementation included.
• Base: develop at D; refresh before separately authorised branch creation.
• Naming policy: local guide, validator and organisation strategy. Static inspection only; validator not run.
• PR template: canonical shared documentation template; local routing names absent pr_documentation.md. Maintainer confirmation before PR creation; do not repair routing here or assume template loading.
• Historical clarification: docs: spec-002 - TOA media library specification closed without merging; docs: TOA media library specification and research (Phase 0–1) subsequently merged related draft material. Neither establishes accepted workflow design, recovered assets, tested rollback or migration approval. Preserve earlier historical paragraphs; this is a clarification, not a rewrite.
• Constraints: preserve unrelated content; no branch creation/reuse/rename, force-push, merge, deployment, extraction, upload, reference replacement or configuration changes.

Expected file changes

Provisional plan. Existing paths read at D; new destination explicitly proposed.

Drafting can use explicitly provisional inputs; final approval depends on reviewed catalogue, storage evaluation and recovery findings. Serialise shared task-file edits and refresh after approved changes. Exclude schema redesign, validation-runbook rewrites and specification-wide reconciliation. Additional files require revised preview.

Existing reports misassign responsive-image scripting to this design issue; that is not implementation authority. Migration, responsive processing and storage configuration remain separate work. Preserve protected references even when documenting future replacement gates.

No protected/locked files, changelog changes or new tests proposed. Locked configuration remains human-controlled and centrally managed workflows untouched. Static inspection only: no tests, builds, recovery or rollback exercise. Future validation requirements or exceptions need agreement. Saving this issue addition may synchronise publicly and requires exact-preview approval; no status, hierarchy, labels, PR associations or pending batch changes.