# Stale Fingerprinted Asset Recovery Step 3 Development Plan

## Stage 1
- Goal: Reproduce the stale HTML/asset mismatch and establish regression coverage before changing request handling.
- Dependencies: Approved Step 2; current static artifact and fingerprinting behavior.
- Expected changes: Add focused tests that distinguish a current fingerprint, an obsolete fingerprint for a known source asset, and an invalid/unknown asset path.
- Verification approach: Run the focused asset and front-controller tests; confirm the current mismatch is represented without changing runtime behavior.
- Risks or open questions:
  - Existing generated files may be stale or untracked in local environments.
- Canonical components/API contracts touched: `AssetFingerprint`, `FrontController`, `tests/LocalAppSmokeTest.php`.

## Stage 2
- Goal: Recover obsolete fingerprinted asset requests safely at runtime.
- Dependencies: Stage 1 coverage.
- Expected changes: Extend the canonical fingerprint resolver and front-controller asset path to identify a stale hash only when its known source asset exists, then direct the browser to the current fingerprinted URL with safe cache semantics. Preserve rejection of unknown paths and arbitrary files.
- Verification approach: Test CSS and JavaScript stale requests, current requests, unknown hashes, unsupported methods, and content-type/cache behavior.
- Risks or open questions:
  - Redirect handling must not create loops or make obsolete URLs permanently immutable.
  - Recovery must remain limited to public assets and recognized fingerprint syntax.
- Canonical components/API contracts touched: `src/ForumRewrite/Host/AssetFingerprint.php`, `src/ForumRewrite/Host/FrontController.php`.

## Stage 3
- Goal: Keep static HTML and fingerprinted assets consistent when artifacts are generated or published.
- Dependencies: Stage 2 committed.
- Expected changes: Adjust the static artifact workflow so generated pages and their referenced assets are published as one consistent artifact set, with replacement ordering that cannot expose a new HTML reference before its asset exists.
- Verification approach: Build a temporary artifact set after changing an asset; verify generated HTML references available files and that replacement leaves the previous set usable until the new set is ready.
- Risks or open questions:
  - The hosting environment may determine whether atomic directory/symlink publication is available; retain the runtime fallback if it is not.
- Canonical components/API contracts touched: `src/ForumRewrite/Host/StaticArtifactBuilder.php`, static artifact layout, deployment-facing build flow.

## Stage 4
- Goal: Add a release-time asset-reference health check and complete end-to-end verification.
- Dependencies: Stages 1–3 committed.
- Expected changes: Validate fingerprinted CSS/JavaScript references emitted by generated HTML, fail or report missing assets clearly, and document the recovery and publication guarantees in the Step 4 summary.
- Verification approach: Run focused tests, the full suite, a generated-artifact check, and a private-style request flow that loads HTML followed by every referenced asset.
- Risks or open questions:
  - Existing unrelated full-suite failures must remain separately identified rather than obscuring asset regressions.
- Canonical components/API contracts touched: `tests/LocalAppSmokeTest.php`, `StaticArtifactBuilder`, `AssetFingerprint`, `FrontController`, Step 4 implementation summary.

## Approval Gate

- Create the Step 4 feature branch only after explicit `Approved Step 3`.
- Commit the approved Step 1–3 planning documents first, then commit each implementation stage with its Step 4 summary update.