docs: media-library - Define media-library validation and handoff #283

Documentation Update Summary

Define validation and operational handoff for the TOA media library, informed by the catalogue, storage and migration workflow.

Current status — 19 October 2026

In Progress. Validation and quickstart documents exist but remain draft guidance—not executed QA or operational handover. Illustrative PASS outputs require clear labelling.

The referenced contracts/validation-metadata-rules.json is absent. Catalogue/schema inconsistencies and obsolete hash-as-node-ID access instructions require reconciliation.

Linked Stories/Tasks/PRs/Epic

Parent: #267. Original artwork extraction and restoration remain in #7. No implementation PR specified.

Milestones & Timeline

Not set. Use the agreed catalogue, storage and migration workflow to inform the guide.

What documentation is needed?

An operational publishing guide covering the agreed workflow, visual comparison against the current website, broken-reference checks and metadata-completeness checks.

Why is this documentation important?

Provide a practical, repeatable validation and handoff process for the TOA media library.

Acceptance Criteria

• Define visual comparison, broken-reference and metadata checks with observable pass/fail criteria.
• Explain treatment of unknown provenance, rights and print suitability.
• Document publishing, maintenance, failure escalation and handoff against agreed workflows.
• Distinguish instructions and examples from actual validation results.

Additional Context

Keep original artwork extraction and restoration in #7; do not duplicate that scope. Ownership and deadlines remain unset.

Definition of Ready (DoR)

• Documentation purpose and recovery boundary are documented.
• Catalogue, provider/migration inputs, reviewer and operational recipient are confirmed.

Definition of Done (DoD)

• Reviewed guidance satisfies the criteria and accurately labels limitations.
• Validation and handover work receive the guide; no unperformed QA is claimed.

Immediate next steps

Align guidance with the implemented image-map extractor, agreed catalogue contract and owner decisions. Define repeatable visual, reference and metadata checks, failure escalation, maintenance, rollback and handoff.

Evidence required

Reviewed instructions, observable pass/fail/unknown criteria, resolved or explicitly deferred contract gaps and confirmed recipients/reviewers. Execution and operational acceptance remain separate evidence.

Confirmed planning boundary — 18 October 2026

Guide drafting may proceed using labelled assumptions. Finalise operational instructions against approved inputs; executed handover follows deployed validation.

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.

Relevant requirements: US4, FR-014–017. T032–T038 provide validation and handoff guidance inputs, not executed QA or a complete operational publishing guide.

Branch instructions

• Repository: lightspeedwp/ThisOneTimeOnAcidCom.
• Implementing target: this issue’s validation and publishing/handoff guidance, not executed QA, recovery or operational acceptance; counterpart GitHub issue 283.
• Parent context: existing media-library coordination relationship only. Retain hierarchy; omit parent identifiers/URLs from branch names, PR titles/bodies and copied prompts. Never use the parent as a native development or closing target.
• Allowed closing targets: none authorised. A future association requires reviewed completion of the whole documentation outcome, including agreed inputs and recipients.
• Branch state: proposed new branch; no existing branch recommended for reuse.
• Branch: docs/media-library-validation-handoff.
• Base: develop, checked at 4ecdb26d9655a48bf000a7c89da2f70383edce87.
• Naming policy: local guide, validator and organisation strategy. docs/ fits the guide-only scope. Static inspection, not executed validation.
• PR template: verified shared documentation template. Explicit selection recommended; symbolic local routing does not prove template application. No local templates proposed.
• Existing work: merged audits are context, not an active implementation match or completion evidence. Do not reuse the mixed-scope findings branch automatically.
• Constraints: planning only; no branch creation/rename, force-push, association changes, merge or deployment authorised.

Expected file changes

Provisional two-file plan. Proposed edits only; path existence is not approval or acceptance.

The extractor resolves image-reference hashes through the file image map, while the access-test script treats hashes as node IDs. Do not present that script as verified recovery proof. The asset validator checks limited PNG headers/dimensions, not the complete metadata contract, provenance, fidelity or rights. Describe limits; do not modify or execute either script here.

The metadata-rules contract is absent: record the dependency rather than creating it. Resolve catalogue terminology through the modelling handoff. Serialise quickstart edits with recovery/provider contributors. GitHub + Netlify remains planning-only; recovery yield is unknown and print-ready delivery deferred. Flag conflicting specification claims without expanding into specification-wide cleanup.

Review plan: trace instructions to inspected source, check examples/links, observable outcomes and side-effect warnings. No execution, uploads, authenticated probes or handover performed. Reviewer eligibility, operational recipients and PR-association effects remain unresolved. Preserve protected images/references, attribution, changelog, centrally managed workflows and human-controlled locked configuration. Any additional file or materially different operation requires revised preview and approval.