# Page fidelity — current-master delivery

Status: DONE — CURRENT-MASTER DELIVERY VERIFIED

## Purpose

Deliver GOLIVE PG-11, PG-12, and PG-13 on fresh current master. This work was previously carried by stale `wt/page-fidelity-delivery`; that branch is reference material only.

## What “page fidelity” means

A translated WordPress Page should remain the **same kind of page structurally**, except for language/content that is intentionally translated. Translation must not accidentally flatten its hierarchy, change publication interaction settings, lose layout/featured-image choices, or inherit stale/unsafe metadata.

For this plugin, fidelity includes:

- **parent hierarchy:** if the source child Page belongs under a parent and a valid translated parent exists, the translated child belongs under that translated parent — never under the source-language parent;
- **safe detach:** if no valid translated parent exists, use parent `0` rather than fabricate a cross-language relationship;
- **page ordering:** preserve `menu_order`;
- **discussion state:** preserve `comment_status` and `ping_status`;
- **layout:** preserve the explicit page template when valid;
- **featured image:** preserve the intended thumbnail relationship under the defined policy;
- **metadata allowlist:** copy only explicitly-safe fidelity metadata, not arbitrary/stale editor locks or unrelated metadata;
- **refresh/regeneration:** existing translated Pages keep these structural attributes correctly when regenerated;
- **failure atomicity:** failed creation/refresh must not leave half-applied hierarchy or metadata mutations.

## Existing reference evidence

Stale branch `wt/page-fidelity-delivery` has two unique commits, notably `c1b1155d6 Complete Page translation fidelity`, but is ~65 commits behind current master. Its old regression contract demonstrates intent around:

- translated parent selection;
- unmapped-parent detach;
- `menu_order`;
- `comment_status` / `ping_status`;
- `_wp_page_template`;
- `_thumbnail_id`;
- rejecting arbitrary metadata such as stale `_edit_lock`;
- inert owned translation shells.

Do not cherry-pick blindly. Reconcile semantics with current Worker/translation-resource/finalizer architecture.

## Ownership boundary

This lane owns PG-11..PG-13 and the minimum production/test seams required for Page fidelity.

It must NOT touch:

- `tests/e2e/remote-stack.sh`, `real-translate.spec.js`, or Connect credential fixture;
- settings/account remediation files;
- manual-translation lock policy;
- ACF/Yoast reconciliation beyond preserving their existing contracts;
- language-root/robots/sitemap/Site Content activation;
- final release packaging or version bump.

The general production-completion plan delegates Page fidelity to this dedicated lane; other agents should not implement PG-11..PG-13 concurrently.

## Tasks

### PF-01 — Current-master seam audit

Inspect current `TranslationBridge`, translation resource handlers/finalizer, Posts/Translations controllers, and current tests. Map old fidelity intent to the actual current creation and refresh paths. Identify obsolete JobSender/receiver-era assumptions and reject them.

### PF-02 — PG-11 creation fidelity

Implement one authoritative Page fidelity preparation/apply seam used by current Page translation creation paths. Preserve safe hierarchy/order/discussion/layout/thumbnail semantics without broad metadata copying.

Tests must prove ordinary non-Page post translation is unaffected.

### PF-03 — PG-12 parent fidelity

Cover at least:

- valid translated parent exists -> translated child attaches to it;
- translated parent may itself be draft if that is the accepted current policy and still a valid translation relation;
- source-language parent is never used as target parent;
- missing/invalid/non-Page/unmapped target parent -> detach to `0`;
- when detachment requires review metadata/reason in current architecture, write the correct bounded reason;
- cycles/self-parent must fail safe.

Resolve the exact “draft parent” rule from current product contracts rather than blindly copying stale branch behavior if the old tests conflict.

### PF-04 — PG-13 refresh fidelity

Prove regeneration/update preserves or clears correctly:

- `menu_order`;
- `comment_status`;
- `ping_status`;
- page template;
- thumbnail;
- any plugin-owned review/fidelity metadata.

Stale source values must be cleared from target when the source no longer owns them, where that is the defined policy. Creation failure and post-refresh failure must not partially mutate fidelity state.

### PF-05 — Regression suite

Recover the strongest old standalone/unit contracts onto current master and add missing cases for the actual current seam. Tests must fail against the pre-fix current-master behavior for defects they claim to catch.

### PF-06 — Browser/runtime proof

Run focused PHP tests, full relevant factory gates, and Page translation browser acceptance through the sanctioned remote E2E path if browser proof is required by the current journey. Do not modify Worker E2E harness files to achieve this.

### PF-07 — Land and retire carrier

Land current-master implementation through repository conventions. Preserve stale branch/WIP in Git history before any carrier cleanup. Update PG-11..PG-13 only from actual evidence.

## Definition of done

Translated Pages preserve the safe WordPress structure and presentation semantics of their source without cross-language hierarchy errors, stale metadata, or partial failure mutations; PG-11, PG-12 and PG-13 can be marked complete from current-master tests/receipts.

## Delivery receipt — 2026-08-19

PG-11, PG-12, and PG-13 are complete on the current-master delivery candidate. The stale `wt/page-fidelity-delivery` carrier remained reference-only; its useful intent was reimplemented against the current `TranslationBridge` / `TranslationFinalizer` architecture rather than cherry-picked.

Implemented behavior:

- new Page translations and owned/private shells inherit only the explicit fidelity allowlist: translated parent, `menu_order`, `comment_status`, `ping_status`, `_wp_page_template`, and `_thumbnail_id`; ordinary posts are unchanged;
- valid linked translated parents, including draft Pages, are retained; source-language, missing, unmapped, non-Page, trashed, self, and cyclic parents fail safe to parent `0`;
- refresh/regeneration converges Page hierarchy/order/discussion/template/thumbnail state, clears stale template/thumbnail state when the source no longer owns it, and preserves unrelated target metadata;
- Page refresh is snapshot-backed and verified; failed application restores the exact prior Page fidelity state; late finalizer failures restore Page fidelity alongside existing core/ACF/SEO rollback;
- current architecture has no Page-specific review-reason contract, so this lane does not invent or persist one. Existing translation review semantics remain unchanged.

Verification on fresh `origin/master` base `78061c1e2` before final landing:

- `php tests/unit/Translation/TranslationBridgePageFidelityStandaloneTest.php` — PASS; the regression was also proved RED against pre-fix current master earlier in this lane;
- `php tests/unit/Translation/TranslationFinalizerCopyOnlyStandaloneTest.php` — PASS, including Page-fidelity application and late-failure restoration;
- core PHPUnit — 128 tests / 886 assertions PASS;
- `factory-gate.sh phpcs` — PASS with no baseline expansion;
- PHP syntax, admin lint, production build, and UI architecture gates — PASS;
- `factory-gate.sh phpstan` — candidate has no Page-fidelity error and reproduces the same eight unrelated current-master failures observed on untouched master; immutable analyzer policy is unchanged, and the legacy non-Page `create_translation()` insert shape remains intact so its pre-existing baseline entry continues to match;
- full standalone/integration runner — Page-fidelity regression passes and core PHPUnit remains green; its remaining nine unexpected failures plus four bootstrap/known-failing cases were reproduced on untouched master and are outside this lane;
- sanctioned browser proof via `e2e-remote` on `debian1`: `page-navigation.spec.js --grep "4 - Translate (Pages tab)" --project=chromium --project=firefox` — **2/2 PASS**, with zero console errors, failed plugin API requests, error toasts, or inline error messages.

The earlier broad `generate-translation.spec.js` smoke was non-authoritative for this slice because it failed on its unrelated Themes-tab journey in both browsers. The focused Pages journey above is the acceptance receipt for PF-06.

## Canonical landing receipt — 2026-08-20

- implementation commit: `01940a99240c98e6fe1d919b0815670e645fc503` (`Complete Page translation fidelity`);
- protected pre-commit gate: remote PHPCS, PHPStan, and slopgate passed on sanctioned buildbox `debian3`, including `IPZ_REMOTE_PHP_GATE_OK` for staged tree `d655a8be020547b851c14bdfb23a480eab2f0025`;
- repository delivery controller: `land` succeeded and published `01940a99240c98e6fe1d919b0815670e645fc503` directly to `origin/master` after secret scanning reported no leaks;
- focused Page regressions passed again on the exact pre-landing `origin/master` base immediately before the protected commit;
- GOLIVE PG-11, PG-12, and PG-13 may therefore be checked `[WORKS]` from canonical current-master evidence.