🧪 Add a local end-to-end publication pipeline integration test

[szmyty]

Summary

Add a deterministic local end-to-end integration test for Reflector's complete publication pipeline.

The Repository Reflection and Synchronization Audit explicitly records that the CI workflows are validated independently, but no local integration test exercises the full publication pipeline as one coordinated flow. The repository currently documents:

• a focused local smoke test for release staging, manifest generation, and checksums
• a remote GitHub Actions dry run for the broader publication workflow

Those are valuable, but they do not provide a single credential-free local test that proves the complete pipeline's component boundaries remain compatible.

Goals

• Exercise the complete local publication path through one canonical test entry point.
• Catch integration drift that isolated unit, smoke, and workflow checks cannot detect.
• Reuse production scripts and task definitions rather than reimplementing the pipeline in the test.
• Keep the test deterministic, credential-free, and safe for local and CI execution.
• Clearly distinguish local integration coverage from hosted deployment and external publication validation.

Scope

Integration-Test Contract

Define the exact locally testable pipeline boundary. At minimum, evaluate whether the test can cover:

1. Canonical metadata and version validation.
2. Paper build.
3. Magazine build, including print output where supported.
4. Publication-readiness and consistency audits.
5. Artifact staging.
6. Release-manifest generation.
7. Checksum generation and verification.
8. arXiv bundle creation and structural validation.
9. GitHub Pages staging preparation.
10. Final artifact inventory and cross-surface consistency checks.

Document any stage that cannot run locally and the reason it remains outside the test boundary.

Test Architecture

Add a repository-level integration test or harness that:

• runs against an isolated temporary workspace or fixture
• invokes the same public scripts and tasks used by the real publication workflow
• does not create a Git tag, GitHub Release, Pages deployment, Zenodo deposition, or arXiv submission
• does not require network access, repository secrets, or external credentials
• verifies expected files, paths, manifests, metadata, checksums, and exit statuses
• fails with actionable diagnostics identifying the stage and expected artifact
• cleans up temporary state
• produces deterministic results across repeated runs

Do not replace focused unit and smoke tests. The new test should complement them by validating composition across stages.

Fixtures and Performance

Prefer the smallest representative fixture that still exercises the real integration boundaries.

If the complete manuscript and magazine make routine execution too expensive:

• define a clearly named slow or integration test marker
• provide a compact synthetic publication fixture
• keep at least one scheduled or explicitly invoked test against representative repository content
• document expected runtime and resource requirements
• ensure the fast canonical test suite can remain practical

Synthetic fixtures must be clearly labeled and must not be presented as validation of the published manuscript itself.

Task and CI Integration

• Add a canonical local task such as an existing repository-convention-compatible integration-test target.
• Use the same entry point in CI.
• Decide whether the test runs on every relevant pull request, on publication-path changes, on a schedule, or through a documented combination.
• Preserve the remote dry-run workflow for hosted workflow validation.
• Preserve the focused release-staging smoke test for fast regression feedback.
• Document the distinction among unit tests, focused smoke tests, local end-to-end integration, remote dry runs, and real release validation.

Documentation and Audit Alignment

Update the relevant documentation and audit tracking surfaces to:

• link the canonical local integration-test command
• explain its coverage and exclusions
• reconcile the limitation recorded in audits/repository-reflection-audit.md
• record follow-up work for hosted or external stages that cannot be simulated safely
• update TODO.md only for work actually completed

Constraints

• Do not publish a release or deployment from the integration test.
• Do not call GitHub, Zenodo, arXiv, or other external services.
• Do not require credentials or network access.
• Do not duplicate production orchestration logic in a test-only implementation.
• Do not weaken existing publication validation to make the test pass.
• Do not conflate a local integration pass with successful hosted deployment or external archival publication.
• Do not make the default developer test loop unreasonably slow without an explicit marker and execution policy.
• Preserve current SPDX, REUSE, fixture, and testing conventions.

Expected File Changes

Likely changes include:

• repository-level integration tests and fixtures
• Taskfile.yml
• relevant test configuration or markers
• the appropriate CI or publication-quality workflow
• docs/publication-infrastructure.md
• docs/release-process.md
• TODO.md

Production scripts should change only when the integration test exposes a real composability, observability, or testability defect.

Validation

• Run the new integration test from a clean local environment.
• Run it repeatedly and confirm deterministic outputs.
• Confirm it succeeds without network access or credentials.
• Confirm temporary files are isolated and cleaned up.
• Confirm expected paper, magazine, manifest, checksum, bundle, and staging artifacts are validated within the declared boundary.
• Deliberately remove or corrupt representative artifacts and confirm actionable failures.
• Run the existing unit and smoke tests.
• Run the repository's canonical validation, linting, and REUSE checks.
• Confirm CI invokes the same integration-test entry point documented for local use.

Acceptance Criteria

• A documented local end-to-end publication integration-test boundary exists.
• One canonical command exercises the locally supported publication stages as a coordinated flow.
• The test reuses production scripts and task definitions.
• Metadata validation, builds, audits, staging, manifests, and checksums are covered where locally supported.
• Unsupported hosted or external stages are explicitly identified.
• The test creates no tags, releases, deployments, deposits, or submissions.
• No network access, credentials, or repository secrets are required.
• Test fixtures and temporary outputs are isolated and deterministic.
• Missing or corrupt artifacts produce actionable stage-specific diagnostics.
• Existing focused smoke and unit tests remain in place.
• CI and local development use the same integration-test entry point.
• Execution policy and expected runtime are documented.
• The audit limitation and TODO.md are updated truthfully.
• Existing tests, publication validation, and REUSE checks pass.

References

• Repository Reflection and Synchronization Audit
• Issue Create Repository Reflection & Synchronization Audit #196 — Create Repository Reflection & Synchronization Audit
• Issue Automate Reflector Release Lifecycle #165 — Automate Reflector Release Lifecycle
• Issue Harden Publication Infrastructure and Release Reliability #169 — Harden Publication Infrastructure and Release Reliability
• Issue Final Boss: Publication Platform Completion & Production Readiness #187 — Final Boss: Publication Platform Completion & Production Readiness
• Issue 🚀 Complete high-priority publication and archival readiness #222 — Complete high-priority publication and archival readiness
• audits/repository-reflection-audit.md
• tests/test_stage_publication_release.py
• docs/publication-infrastructure.md
• docs/release-process.md
• .github/workflows/publication.yml

TODO.md

Update the repository root TODO.md as part of this work:

• Check off the local end-to-end publication integration-test task only after the full declared boundary is exercised.
• Preserve separate follow-ups for hosted deployment and external publication validation.
• Record any stages excluded from local execution with their validation owner.
• Preserve unrelated TODO items.