docs: media-library - Reconcile Spec Kit planning decisions #407

Documentation Update Summary

Reconcile the media-library Spec Kit planning documents with the owner decisions recorded on 18 October 2026. Produce an evidence-backed proposed diff before applying changes.

This issue covers specification/documentation reconciliation—not asset recovery, provider configuration, migration or implementation.

Linked Stories/Tasks/PRs/Epic

Parent: #267.

Repository: lightspeedwp/ThisOneTimeOnAcidCom.

Feature: media-library specification directory.

Supporting files:

• toa-media-library-speckit-reconciliation-brief.md
• toa-media-library-claude-prompt.md

The brief reflects revision 4ecdb26d; re-check current sources before proceeding. Existing child issues retain responsibility for their delivery outcomes.

Milestones & Timeline

Status: Todo. Estimate intentionally unset. No milestone or deadline assigned.

What documentation is needed?

Reconcile the specification, research, plan, tasks, data model, schema, provider/validation contracts, quickstart and checklists.

Apply these recorded boundaries consistently:

1. GitHub + Netlify is approved for planning only; provider evaluation and separate implementation approval remain required.
2. Recovery yield is unknown. Assess print suitability now, defer print-ready delivery and document gaps. No fixed recovery or print thresholds are established.
3. Evaluation, initial modelling and reversible planning may proceed in parallel. Final schema approval requires recovered-asset validation; configuration/migration require approved inputs and safeguards; handover follows deployed validation.

Also reconcile unsupported completion claims, the 61-lightspeedwp/tour-operator#415-task semantic crosswalk, deferred FR-009/FR-012/FR-017 coverage and the missing T023 metadata-rules contract.

Why is this documentation important?

Conflicting decision states, assumed recovery results and illustrative PASS outputs currently risk being mistaken for approved requirements or completed delivery.

Acceptance Criteria

• Documentation is clear, accurate, and up-to-date
• Includes code examples/screenshots if applicable
• Documentation is accessible and easy to find
• Changelog entry prepared for PR if user-facing update
• PR uses correct branch prefix (docs/)
• PR description updated with relevant details
• Changelog entry prepared for PR (if applicable)
• Labels/types match org standards
• Q1–Q3 agree across the affected artefacts.
• Recovery claims, numeric thresholds and checked-task evidence are classified as verified, partial, drafted or outstanding.
• The semantic task crosswalk preserves scope without inventing mappings or completion.
• Deferred requirements and missing contract coverage are explicitly addressed or recorded as unresolved.
• Catalogue model, schema and runbook inconsistencies are identified and proposed corrections reviewed.
• Claude/Spec Kit integration, command availability and hooks are verified before any command is considered.
• A proposed diff, validation plan and remaining questions are returned for approval before edits.

Additional Context

Claude prompt

Prepare a read-only reconciliation proposal for the media-library
feature in lightspeedwp/ThisOneTimeOnAcidCom.

Read the attached reconciliation brief and prompt package. Use the
current TOA-269 decisions as authority; attachments are dated drafts,
not proof of current state or completed work.

Preflight:
1. Read the repository's AGENTS.md, CONTRIBUTING and relevant guidance.
2. Compare current sources with the brief's revision:
   4ecdb26d9655a48bf000a7c89da2f70383edce87.
3. Inspect Spec Kit configuration, installed integration/version,
   generated command definitions, overrides and hooks.
   Checked-in configuration identifies Gemini and version 1.0.13.
   Do not assume Claude slash commands exist.
4. If material source changes or missing authority prevent a reliable
   proposal, report the discrepancy and stop the affected work.

Do not execute Spec Kit commands. If Claude integration is unverified,
report that limitation; do not invent syntax or install anything.

Compare the relevant specification, research, plan, tasks, model,
contracts, quickstart and checklists against the recorded decisions:
- GitHub + Netlify is for planning only; evaluation and separate
  implementation approval remain required.
- Recovery yield is unknown. Assess print suitability now, defer
  print-ready delivery and avoid unapproved numeric thresholds.
- Permit bounded parallel evaluation/modelling/reversible planning.
  Final schema requires recovered-asset validation; configuration
  and migration require approved inputs and safeguards.

Return:
- A minimal proposed unified diff, not applied edits.
- Evidence and rationale for each correction.
- Proposed treatment of unsupported checked tasks, preserving IDs.
- The semantic 61-to-49-task crosswalk where evidence supports it;
  mark uncertain mappings explicitly.
- Deferred requirement and metadata-contract gaps.
- A validation plan covering documentation, schema and runbook
  consistency, with execution still requiring approval.
- Remaining decisions and limitations.

Preserve useful content, references, task IDs and unrelated schema
constraints. Illustrative examples are not executed results.

Do not edit files, run state-changing helpers, implement code,
recover/upload assets, configure services, change image references,
create branches/issues/PRs, commit, push, merge or update Linear.
Stop after presenting the proposal for approval.

Template branch, PR and changelog criteria apply only to a separately authorised repository contribution and its verified conventions. They do not authorise that contribution or automatic parent/related-record updates.

Definition of Ready (DoR)

• Documentation need is clear and well-defined
• Related docs/issues or files linked
• Acceptance criteria listed
• Estimate added if relevant — intentionally unset
• Milestone/release assigned (if applicable)

Definition of Done (DoD)

• Documentation meets org standards and guidelines
• Changelog entry prepared for PR (CHANGELOG.md)
• Documentation reviewed for clarity and accessibility
• Screenshots/code examples included if relevant
• PR uses correct branch prefix (docs/)
• PR uses the correct PR template based on type:docs PR label or linked issue type or linked issue type:docs label
• Branch deleted after merge
• Linked issue(s) updated with latest status and closed after merge
• The related epic should not be closed, instead updated with a comment to reflect the closed issue