feat(acquire): attach acquisition-provenance referrer on mirror

[toddysm]

Implements the acquisition-provenance referrer feature. For every image acquired (mirrored) from an external registry into quarantine/<image>, attach an OCI 1.1 in-toto referrer recording where it came from and how it was acquired.

Design: docs/architecture/acquire/acquisition-provenance.md · Tracking: #140

What changed

• New composite action .github/actions/attach-acquisition-provenance — builds an in-toto Statement (artifact type application/vnd.in-toto+json, predicate type https://toddysm.com/acquisition-provenance/v0.1) per subject and oras attaches it to the index/tag and each per-platform child manifest. Per-platform statements also carry platformSourceDigest. Key fields are duplicated as com.toddysm.acquisition.* discovery annotations.
• _mirror-image.yml — new record_acquisition_provenance input (default true); setup-oras condition widened to include it; new Attach acquisition provenance step gated on record_acquisition_provenance && steps.mirror.outputs.copied == 'true'. Scoped to external → quarantine acquisition only (promotion uses the promote workflows and is unaffected). No new secrets.
• Docs — design doc + consumer reference (docs/reference/acquisition-provenance.md), action catalogue + terminology rows in workflow-actions.md, and image-mirror-workflows.md Implemented / Not-implemented updates.

Predicate fields

Core (always): source ref/registry/repository/tag/digest, destination ref/digest, acquiredAt, runUrl. Plus actor, workflow (name/runId/runAttempt), copyMethod (crane|oras), copyReferrers, sourceAuthenticated, and per-platform platformSourceDigest.

Validation

• actionlint clean on _mirror-image.yml.
• shellcheck -S warning clean on the action's embedded script.
• jq predicate construction verified locally (valid in-toto Statement JSON).
• Markdown link-check: 0 dead links.
• get_errors clean on both YAML files.

Closes #141, closes #142, closes #143. Part of #140.

[Copilot]

Pull request overview

This PR implements “acquisition provenance” for the acquire/mirror flow by attaching an OCI 1.1 referrer (in-toto Statement) to mirrored images in quarantine/<image>, capturing where the image came from and how/when it was acquired.

Changes:

• Adds a new composite action to generate and oras attach acquisition-provenance in-toto statements at both index/tag and per-platform manifest levels.
• Wires the action into the reusable _mirror-image.yml workflow behind a new record_acquisition_provenance input (default true).
• Adds/updates architecture and reference documentation describing the artifact format, fields, discovery annotations, and retrieval commands.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
.github/actions/attach-acquisition-provenance/action.yml	New composite action that builds in-toto Statements and attaches them as OCI referrers (index + per-platform).
.github/workflows/_mirror-image.yml	Adds record_acquisition_provenance input; installs ORAS when needed; calls the new action after a mirror.
docs/reference/acquisition-provenance.md	New consumer-facing reference describing the referrer, fields, annotations, and retrieval commands.
docs/reference/README.md	Adds acquisition provenance to the reference index.
docs/reference/workflow-actions.md	Adds the new action to the action catalogue and documents its inputs.
docs/architecture/acquire/acquisition-provenance.md	New/updated design doc marking the feature as implemented and specifying statement/predicate details.
docs/architecture/acquire/image-mirror-workflows.md	Updates mirror workflow behavior documentation to include acquisition provenance and adjusts non-goals.
docs/architecture/acquire/README.md	Adds acquisition provenance under “Supply Chain Observability”.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.