epic: media-library - Define asset recovery and library strategy #267

Epic Summary

Define and deliver an evidence-based media-library strategy for lightspeedwp/ThisOneTimeOnAcidCom, supporting website delivery and book-publishing assets.

Inventory and recover images used on the published Figma site and the website. Distinguish originals from derivatives, document provenance and usage rights, and preserve protected references until replacements are verified.

Current status — 19 October 2026

In Progress. All 11 specification/design artefacts exist on develop at audited revision 4ecdb26d. PR #285 merged; PRs #294 and #297 closed without merging. Earlier specification material entered through commit 6d932f5a, with later design material added through PR #313. Closed PR #297 does not mean its related material is absent from the repository.

Catalogue, pilot-selection and recovery-support tooling also exist. The source inventory contains 128 literal Figma-hash references covering 56 distinct IDs, matching the full catalogue. All catalogue recovery statuses remain pending, with zero dimensions. Tracked evidence does not establish completed recovery; external execution remains unknown.

The existing 002 package is the reconciliation starting point, not an approved delivery baseline. Its decision states, task markers, catalogue/schema contracts and readiness claims require review.

The 18 October owner decisions remain authoritative:

• GitHub + Netlify is a planning assumption only.
• Recovery yield is unknown; assess print suitability and document gaps, with print-ready delivery deferred.
• Evaluation, initial modelling and reversible planning may overlap. Configuration and migration require separately approved inputs and safeguards.

Outstanding work is recorded in the epic: reconcile conflicting decisions, inventory counts, task evidence, coverage and readiness gates; validate the preserved design artefacts; and resolve the successor branch/PR before repository work begins.

No acceptance or completion checks should be newly marked complete on this evidence. Closing this chat does not close the epic or authorise implementation.

The earlier planning package in docs: TOA media library specification and implementation plan has 61 unchecked tasks. docs: spec-002 - TOA media library specification has 49 tasks, ten marked complete, but conflicting decision states and missing supporting evidence prevent treating it as an approved delivery baseline. Reconcile the packages before implementation proceeds; evaluation, initial modelling and reversible planning may continue in parallel.

Additional Context

Proposed approach

Evaluate storage for original artwork, photography and print-quality assets, CDN delivery of optimised derivatives, and a version-controlled catalogue. Use GitHub + Netlify for planning only; retain provider evaluation, visual upload/tagging assessment and separate implementation approval gates.

Catalogue stable IDs, Figma sources, filenames, dimensions, formats, website/chapter usage, captions, alt text and verified credits/rights. Record unknown information explicitly; do not invent it.

Read-only extraction pilot

Evaluate Figma skills and authenticated access against the editable Make project, not only the published site.

Record recoverable originals, derivatives, inaccessible assets, access requirements and manual-export gaps. Do not assume automated recovery of every original.

The pilot must not modify repository files, replace references, upload to another service or change the Figma project.

Acceptance Criteria

• Website image references and usage are inventoried and mapped to available Figma sources; conflicting historical counts are reconciled.
• The read-only pilot records recoverable originals, derivatives, inaccessible assets and manual-export requirements.
• Recovery quality and print suitability are assessed against confirmed requirements.
• The catalogue contains the metadata listed above and distinguishes originals, derivatives and unverified information.
• The initial catalogue model and final schema are validated against representative recovered assets.
• Provider options are evaluated against recovery findings, website delivery, upload/tagging and book-export requirements; approval is recorded.
• Migration design covers verified mappings, deduplication, rollback and protection of existing references.
• Validation covers visual comparison, broken references and metadata completeness.
• Publishing, maintenance, escalation and handoff procedures are documented.
• Every child issue satisfies its own acceptance criteria before epic closure.

Linked Child Issues/Stories/Tasks/PRs

Existing children: #7, #279, #280, #281, #282, #283, #288, #289, #290, #291 and #292.

Coordinate original-artwork recovery/restoration through #7. Keep skills evaluation, catalogue definition, provider evaluation, migration design, validation and implementation distinct.

Related PRs: docs: TOA media library strategy audit and recommendations, docs: TOA media library specification and implementation plan and docs: spec-002 - TOA media library specification. These are documentation contributions, not closing implementation evidence.

Milestones & Timeline

No milestone, deadline or epic estimate is set.

Evaluation, initial modelling and reversible planning may proceed in parallel. Finalise the schema using recovered-asset validation. Configuration and migration require approved inputs and safeguards; handover follows deployed validation.

Dependencies / Blockers

• Authenticated Make access and representative recoverable assets remain to be verified.
• GitHub + Netlify planning approval is recorded; provider evaluation, cost verification and implementation approval remain outstanding.
• Recovery yield remains unknown. Assess print suitability now, defer print-ready delivery and document gaps; technical print thresholds remain unconfirmed.
• Apply the recorded parallel-planning boundary; final schema approval requires recovered-asset validation, and implementation requires approved inputs and safeguards.
• docs: TOA media library specification and implementation plan has 61 unchecked planning tasks and Phase 0 remains pending. docs: spec-002 - TOA media library specification has 49 tasks, ten marked complete; conflicting decision states and missing supporting evidence require reconciliation before treating either package as an approved delivery baseline.
• Documentation readiness claims and missing acceptance scenarios require reconciliation.

Definition of Ready

• Epic outcome and website/book-publishing scope are defined.
• Existing children and all three related documentation PRs are identified.
• Read-only safeguards and known dependencies are documented.
• Authenticated access and representative source assets are verified.
• Recovery and print-quality baselines are confirmed.
• Planning approval is distinguished from outstanding provider evaluation, upload/tagging assessment and implementation approval.
• The recorded parallel-planning boundary and downstream approval gates are reconciled across the delivery artefacts.
• Required phase reviewers and approvers are confirmed.

Definition of Done

• Every acceptance criterion has linked evidence and maintainer approval.
• All 11 children are completed and closed against their own requirements.
• Recovery, catalogue, provider and migration decisions agree across records.
• Applicable QA results, manual-export gaps and accepted limitations are recorded.
• Operational documentation and handover are complete.
• Relevant delivery PRs are reviewed and merged.
• Applicable changelog requirements are satisfied.
• The epic records the final outcome and evidence before closure.

Immediate next steps

Reconcile the existing package against the recorded Q1–Q3 decisions. Classify task evidence as drafted, implemented-but-unverified, verified or outstanding. Confirm permitted authenticated recovery and sample handling, obtain representative evidence, then reconcile the catalogue contract and downstream approval gates.

Evidence required

Asset-level recovery files/manifests; verified provenance and usage mappings; consistent catalogue/schema validation; provider/workflow findings and approval; authorised configuration/migration results; deployed validation and operational acceptance. File presence and merged support tooling do not establish epic completion.

Owner decisions — 18 October 2026

Q1 — Planning assumption: Use GitHub + Netlify for planning only. Provider evaluation and separate implementation approval remain required. This does not authorise purchases, external uploads, configuration changes or migration.

Q2 — Recovery and print: Recovery yield is unknown. Assess print suitability now, defer print-ready delivery and document gaps. No recovery count, percentage, DPI, format or colour-space threshold is established by this decision.

Q3 — Sequencing: Evaluation, initial modelling and reversible planning may run in parallel. Finalise the schema using recovered-asset validation. Configuration and migration require approved inputs and safeguards; handover follows deployed validation.

These decisions resolve the planning questions, not the underlying research, recovery, validation or implementation work. Documenting this sequence does not change issue relationships.

Reconcile the packages before implementation proceeds; reversible planning may continue in parallel.

Specification references

• 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.

Package scope: FR-001–018 and T001–T049. Decision states, checked-task evidence, task dependencies and coverage require reconciliation before adoption as an approved delivery baseline.

Audit sources: research, requirements checklist and specification-quality checklist. Pending decisions, unsupported completion claims, circular readiness gates and missing design outputs remain unresolved.

Delivery-baseline reconciliation checklist

The owner decisions are recorded: GitHub + Netlify is a planning assumption only; recovery yield remains unknown; print-ready delivery is deferred; evaluation, initial modelling and reversible planning may overlap. The checks below track outstanding evidence and approval—not renewed approval of those decisions.

1. Reconcile the specification baseline

• Use the existing 002 package on develop as the reconciliation starting point, preserving historical sources.
• Align specification, research, plan, tasks and checklists with the recorded owner decisions.
• Produce a semantic crosswalk between the 61-task and 49-task packages, preserving required outcomes and task identifiers.
• Map every requirement to the relevant child issue, deliverable and validation evidence.
• Classify task evidence as drafted, partial, verified or outstanding; justify each completion marker.
• Add observable acceptance scenarios for FR-009, FR-012 and FR-017; resolve the missing T023 metadata-rules contract.
• Confirm the successor branch/PR and obtain approval for the exact repository-edit scope before changes begin.

2. Validate provider and publishing assumptions

• Evaluate GitHub + Netlify without treating the planning assumption as final provider approval.
• Verify storage, bandwidth, build and Git LFS costs, limits and operational constraints.
• Assess visual upload/tagging, replacement, website delivery, original preservation and book-export workflows.
• Record representative evaluation results; distinguish proposed tests from executed trials.
• Document the recommendation, accepted trade-offs and approver.
• Obtain separate authorisation before purchases, external uploads, configuration or migration.

3. Establish recovery evidence and print suitability

• Reconcile 128 reference occurrences, 56 distinct IDs and the historical 75-reference claim using reproducible inventory evidence.
• Confirm permitted authenticated access, extraction scope and sample-handling safeguards before recovery activity.
• Record asset-level recovery outputs: originals, derivatives, partial recovery, inaccessible assets and manual-export gaps.
• Verify dimensions, format, source, usage mappings, provenance and rights; explicitly retain unknown values.
• Substantiate previous recovery claims, including the claimed 12-asset pilot, or classify them as unverified.
• Report measured recovery yield without assuming a target count or percentage.
• Assess print suitability from available evidence; record unknown requirements and gaps without making deferred print-ready delivery a current completion gate.

4. Validate design contracts and phase gates

• Validate catalogue/schema compatibility, required fields, entity constraints and metadata rules.
• Distinguish illustrative examples and PASS results from executed validation.
• Confirm that parallel work has independent outputs, satisfied prerequisites and no conflicting same-file edits.
• Complete recovered-asset validation before final schema approval.
• Review migration mappings, deduplication, protected references, rollback and approval safeguards before configuration or migration.
• Record actual validation results, limitations and reviewer approval before adopting a delivery baseline.
• Require deployed validation and operational acceptance before handover or epic closure.

Completion rule: file presence, merged tooling and recorded planning decisions do not establish completed recovery, provider trials or implementation. Existing acceptance criteria, DoR and DoD remain in force.

Design recovery packet — unvalidated draft

Source: PR #297 final commit c4256cb3. Five original artefacts are preserved byte-for-byte as reviewable draft design material, not verified recovery, executed validation or production readiness. Original paths are relative to .github/specs/002-media-library/.

• data-model.md
• provider-evaluation.md
• validation-checklist.md
• quickstart.md
• catalogue-schema.json
• recovery-instructions.md

Extract missing design detail and reconcile catalogue-envelope versus asset validation, required fields, entity constraints and schema/runbook inconsistencies. Preserve existing specification content and distinguish original snapshots from proposed corrected drafts.

Compare PR #294's 61-task breakdown with the consolidated 49 tasks and produce a semantic crosswalk. Preserve lifecycle, versioning, storage decisions, provider trials, pilot validation, extraction measurements and handoff requirements. Address deferred FR-009/FR-012/FR-017 scenarios and the missing T023 metadata-rules contract explicitly.

Classify task evidence as drafted, partial, verified or outstanding. Illustrative PASS results are not executed validation. Design authorisation does not establish completed asset recovery or provider trials. No repository restoration, implementation, merge, PR closure or task-completion change is performed by attaching this packet.

Specification disposition — 19 October 2026

Historical review record: preserve this assessment and proposed edits as history. Current repository availability is described above. Historical absence or readiness statements do not override current evidence or the recorded owner decisions.

PR #297 is closed and unmerged. Its specification and preserved design packet remain draft reference material, not an approved delivery baseline or evidence of completed recovery, validation, provider trials or implementation.

Retain the 18 October owner decisions: GitHub + Netlify is a planning assumption only; recovery yield remains unknown; print suitability should be assessed, while print-ready delivery remains deferred.

Before adopting a delivery baseline, reconcile decision states, unsupported completion claims, the 56/75 inventory counts, coverage of all 11 child outcomes, task dependencies and the overlapping planning packages. Validate the preserved design artefacts rather than treating their existence as completion.

Recovery, final schema validation, provider approval, configuration, migration and operational handover remain outstanding under their existing acceptance criteria. Protect existing references. Any future specification-only merge requires a separately approved boundary and explicit deferrals.

This assessment does not authorise reopening or merging the PR, implementation, or closure of the epic or its children.

Pending 002 reconciliation handoff — 19 October 2026

Historical review record: preserve this assessment and proposed edits as history. Current repository availability is described above. Historical absence or readiness statements do not override current evidence or the recorded owner decisions.

This preserves the 18 October proposal against revision c4256cb3be21e1b47d9f138d525f39a4a38e5225 of the 002 specification package. Repository changes have not been executed. PR #297 was verified closed without merging during that review. Recheck current repository/PR state before work; successor branch/PR selection remains unresolved.

Saving this handoff does not authorise commands, branches, commits, uploads, deployment, implementation or new records. Preserve unrelated content, historical references and protected images.

Specification

In spec.md, preserve original questions/options as history. Replace pending responses and conflicting assumptions with the recorded Q1–Q3 decisions. Set status to “Draft — Owner decisions recorded; reconciliation and evidence review required”.

Exact requirement replacements:

• FR-004: “Recovery workflow MUST assess and document print suitability from available asset evidence, marking unverified requirements and gaps explicitly. Print-ready delivery is deferred.”
• FR-013: “Assessment MUST document each provider’s preservation of recovered originals and potential print-workflow limitations; print-ready delivery and unconfirmed technical thresholds are not current acceptance gates.”
• SC-001: “For the inventoried recovery scope, document assets recovered, partially recovered, requiring manual export or unrecoverable, with evidence, metadata and gaps. Recovery yield remains unknown until measured; no assumed target count or percentage establishes success.”

Readiness gates remain unchecked until decisions are reconciled, evidence requirements are explicit and any configuration/migration has separately approved inputs and safeguards.

Research and plan

In research.md, replace contradictory resolution summaries with Q1–Q3. Replace “awaiting responses”/“Phase 0 complete” conclusions with “Owner decisions recorded; supporting research and validation remain unverified”.

Remove superseded recovery-yield, print-threshold and timeline-saving assertions from resolution summaries. Preserve actual findings and unresolved evidence gaps. Owner responses may be marked recorded; research/pilot completion, cross-artefact consistency and implementation readiness may not.

In plan.md, use:

“Evaluation, initial modelling and reversible planning may overlap → recovered-asset validation → schema finalisation → separately approved configuration/migration → deployed validation → handover.”

Recovery yield requires measured evidence. Assess print suitability and gaps without requiring print-ready delivery. Sample-dependent validation waits for recovered evidence.

Tasks

In tasks.md, preserve IDs and use:

• T004: “Document recovery yield as unknown; record measured recovery outcomes and gaps only when supporting evidence is available.”
• T005: “Assess print suitability from available recovered samples and document limitations; defer print-ready delivery and unconfirmed technical thresholds.”
• T006: “Document bounded parallel planning and the validation, schema-finalisation, configuration/migration and deployed-handover gates approved in Q3.”
• T007–T009: Record corresponding Q1–Q3 using their saved exact wording.
• T028: “Distinguish current website requirements from deferred print-ready delivery; document print-suitability findings and unresolved criteria.”
• T031: “Evaluate GitHub + Netlify as the planning baseline without predetermining the recommendation or bypassing implementation approval.”
• T033: “Define assessment criteria and explicitly unresolved print requirements; document gaps without enforcing an unapproved print-ready threshold.”
• T041: “Document observed manual-export gaps and measured recovery outcomes; yield remains unknown until evidenced.”
• T049: “Repeat the reviewer-owned quality review after design updates; this does not substitute for the required pre-design readiness review.”

Proposed marker changes: uncheck T001–T005 and T010 pending evidence/review; retain T006–T009 only after verified documentation edits. Preserve other markers.

Remove parallel markers from T011–T013, T016–T017, T026–T027 and T032–T035. Parallel work requires independent outputs, satisfied dependencies and no concurrent same-file edits.

Checklists and design outputs

• requirements.md: record Q1–Q3; preserve reviewer marks as historical, not renewed validation.
• specification-quality.md: align CHK008/022/044/047–049 with the decisions. Preserve reviewer marks; re-review CHK047–050 and CHK058–CHK060.
• data-model.md: replace mandatory print-ready assertions with assessment, unknowns and deferred-delivery wording.
• catalogue-schema.json: label examples illustrative; preserve fields/constraints and flag conflicting numerical thresholds for separate review.
• provider-evaluation.md: the planning baseline is not a predetermined outcome; account creation, uploads and purchases require separate authorisation.
• validation-checklist.md: scores report findings, not execution permission; deferred print-ready gaps alone do not fail current delivery.
• quickstart.md: label samples, commands and reports illustrative; replace summary “PASS” with “Not executed / evidence required”; remove implied execution readiness.

Separate follow-ups remain: broader traceability gaps, T039 ownership conflict, schema/validator correctness, unsupported quotas/durations and task crosswalk. None is silently resolved by recording this handoff.

Unanswered clarification questions

The recorded answers to Q1–Q3 remain unchanged. These questions clarify outstanding recovery inputs, not new planning commitments or permission to execute.

1. Who confirms authorised access to the editable Figma Make project?
2. Which read-only recovery method is permitted for the pilot?
3. Where may representative samples be saved, and which pages or components should they cover?
4. Who reviews the sample-to-source mappings and recovery findings?
5. What evidence and approval are required before moving beyond the pilot, given that recovery yield and print suitability remain unverified?