jobtrackingapp/docs/redesign/phase-5/READINESS_GATES.md

# Phase 5 readiness gates

Planning at `2a2f9e48052c562ef599825458d0d3a6f9f9fc61`. **None of these gates is closed by writing this document.** [P4-06](../phase-4/p4-06/README.md) permits planning, not unqualified implementation. Gate IDs below are planning references, not replacements for defect/PRES IDs.

## G-SHELL — P5-00, before P5-01 starts

Successor evidence: [P5-00 implementation and validation](p5-00/README.md). The five shell defects below are addressed, including the shared 1024px threshold and open-drawer resize lifecycle. The separate P5-00-D01 clock fixture is deterministic and the backend baseline is restored to **916/916**. P5-01 has an explicit **GO**. The following table preserves the original required evidence.

P5-00 is required. Resolve these narrowly against the **existing** shell first, with regression evidence before regrouping or restyling it. This separates baseline remediation from redesign regressions.

| Existing condition | Bounded prerequisite / responsible owner | Required exit evidence |
|---|---|---|
| P4-06-O01: persisted desktop collapse hides mobile labels and puts first focus under the app bar | `AppShell`: separate the mobile presentation decision from the saved desktop preference; correct drawer/header focus occlusion using existing MUI mechanics | Collapse → reload → 320/390px → open drawer: all labels visible, first and last links reachable and hit-testable, focus not obscured; Escape returns to trigger; return to desktop retains collapse. Expanded control and 767/768 boundary also pass |
| P4-06-O02: long synthetic admin version badge overlaps narrow header | Same owner: bounded metadata reflow/disclosure; retain admin-only version and commit access | Admin/non-admin, long name/version, EN/NB, both themes at 320px. No logo/control overlap; no loss of metadata or accidental public exposure. Do not claim actual production badge overlap was proven |
| P4-02-D01: command results render non-list children under a list | `QuickCommandDialog`: correct list/result and empty-state semantics using native/MUI elements, retain existing callbacks | Loaded, empty and keyboard result activation; axe `list` finding absent; Add still opens review without POST, company opens `?edit=id`, job opens its exact ID; focus return works. Arrow-key command expansion belongs to P5-02 |
| P4-03-D01: light Redo Tooltip contrast 3.89:1 | Shared `theme.ts` Tooltip foreground/background pair only | Actual loaded Redo plus shell/table tooltip in both themes, hover and focus: ordinary text ≥4.5:1; remove only the repaired narrow expected contrast exception after proof. Preserve tooltip naming/focus and other semantic pairs |
| P4-04-O01: fixed toast overlaps bottom actions | `toast.tsx`/its existing Snackbar placement boundary: smallest placement/reserved-space treatment needed for actionable feedback and underlying actions to remain reachable | Trigger export toast while Connections is visible at 320/390px and desktop; inspect while toast is **open**, keyboard/hit-test both actions, dismiss/action callback and return. Waiting 3.5 seconds is not repair. Keep message lifetime/provider/auth ownership; no notification framework |

These five conditions share shell exposure, not one architectural root cause. Implement/review them as small sub-diffs in one readiness checkpoint; do not create a general overlay manager. If toast placement requires broad page architecture, pause that item and report the concrete blocker rather than hiding it in P5-01.

Also extend the existing real-App fixture for collapse, drawer close versus route selection, command/account/notification disposal on account switch, dirty-navigation Cancel/Discard and theme/language changes while editing. Preserve providers and router lifetime. Current router memoization still depends on table page-size/column preferences; do not change those owners in P5-00/01. Characterize their behavior for P5-03 separately.

Exit: focused reproduction now passes, no general axe exclusions, final complete baseline passes with count deltas explained, EN/NB × light/dark shell evidence reviewed, issue statuses updated individually. P2-D01 remains the separately identified expected failure. **P5-01 is not cleared at this planning checkpoint.** A successful, separately authorized P5-00 checkpoint is its entry gate.

## G-JOBS — before table/board consolidation

**Current query gate: GO after [P5-04b readiness](p5-04b-readiness/README.md).** Both existing endpoints now use one server query and native membership/refresh/ownership evidence passes. [P5-04b integration](p5-04b/README.md) uses that unchanged contract in the shared workspace. Full Board population remains O(N), not one Table page; see the explicit performance ceiling. The paragraphs below preserve the original prerequisite and why the readiness checkpoint was necessary.

Before P5-03, extend PRES-J05/J06 behavioral coverage for saved-view create/select/delete, filtered selection, partial bulk failures, column/page preferences, custom-status URLs, Back/refresh, capture review without writes and 320px actions. Preserve current local Comfortable default; density is neither server-persisted nor a CV setting.

Before P5-04b, prove the actual data contract. `JobTable` calls paginated `/jobapplications` with search/company/status/location/readiness/follow-up/sort/deletion filters. `KanbanBoard` calls `/jobapplications/board` without those parameters; that API accepts only `includeDeleted`, returns all matching non-deleted records by default and has its own ordering. **Parity does not exist today.**

P5-04a can restyle the board at `/kanban` using its existing data. P5-04b is blocked on a separately reviewed, owner-scoped read contract supporting the same filter population without silently changing the all-record board into one table page. Define completeness, stable ordering, bounded loading/pagination, page-size interpretation and mutation refresh; test more than 25 jobs, unknown statuses, filtered-out moves and partial failures. No browser crawl across every table page, client-only approximation of readiness, or redirect with silently dropped filters. If backend work is required, authorize it separately; no schema or generic query framework is implied. Keep `/kanban` live until this proof exists. This gate does not delay Dashboard.

## G-PACKAGE — native preservation before package/tailoring restructuring

Successor: [P5-08b readiness native proof](p5-08b-readiness/README.md#native-preservation-invariants-and-proof). Real SQLite capture, post-source-mutation frozen read/download, native account ZIP extraction/manifest, ownership denial and partial-copy failure/retry are now exercised. The paragraphs below retain the original failed prerequisite; final results and the intentional P2-D01 transition are owned by the successor record. This proof does not close CV revision or PDF geometry gates.

P2-D01 is reproduced SQLite `DateTimeOffset` ordering failure in `ApplicationAssetsService.GetTailoringPlanAsync` and `SubmittedApplicationPackageService.CaptureAsync`. Existing service tests do not prove native success. The browser expected-failure branch is entered only for the observed capture 500; its historical archive checks have not run successfully.

Required separately authorized repair/proof:

1. Real disposable API: account, canonical profile, two variants, job, cover letter, answer draft and attachment; tailoring GET and native capture succeed.
2. Record package identity/source versions; mutate live CV/profile/letter and delete live attachment. Frozen HTML/letter/answers and exact archived binary stay unchanged and downloadable.
3. Cross-owner read/reference/download denied; detach preserves variant; current single-job CV association is not converted into many-to-many. Source-copy failure and retry are explicit, not a successful incomplete package.
4. Native restore/readback and backend/provider compatibility tests pass. Remove P2-D01 annotation only after the original failure and post-capture assertions pass; record the intentional browser count transition.

Blocks P5-08b section/application/document restructuring, related CV tailoring changes, and any future global document index. Does **not** block P5-00–03, P5-04a, existing-data P5-06/07 or P5-08a's bounded header/overview work. No package changes in the shell or dashboard.

## G-CV-REV — server revision safety before broad CV migration

Successor: [P5-09 readiness](p5-09-readiness/README.md#revision-defect-boundary-and-recovery) protects CV save/restore with an expected version and atomic EF concurrency token on the existing column, with cross-client rejection and draft recovery evidence. **CV revision gate satisfied locally; related canonical-profile/job lost-update contracts remain separate.** G-CV-RENDER still blocks P5-09–14. No B07 or schema migration.

Original planning state: `CvVariantService.SaveAsync(owner,id,name,settings,source,ct)` owner-loaded and incremented `Version` without an expected-revision comparison. Restore called Save. The browser queue serialized one mounted editor only. B02 account identity, stale-record conflicts and creation idempotency remain three separate contracts.

Required CV proof, now supplied by the successor: two independent same-account clients load vN; A saves vN+1; B's stale save/restore cannot overwrite A; deterministic conflict/reload/review handling preserves B's unsaved work; canonical-source edits and variant resets have explicit version semantics; legitimate retry/reload/history/undo succeed. Owner isolation must continue to hold. Relevant job/profile lost-update semantics remain separate and must be resolved before **changing their persistence**, not silently rebuilt by a UI slice.

This is separate integrity work, not authorization to start B07 or implement a concurrency framework. Any schema requirement invokes existing restore/rollback readiness first. Serialize all edits to `CvBuilderEditor` with that work. Blocks P5-09–14. Shell-only route entry and the existing isolated preview keyboard protection can remain in use meanwhile.

## G-CV-RENDER — geometry, templates and real output

Current successor: [pagination-fidelity repair](p5-09-pagination-readiness/README.md). Native preview fragmentation reuses renderer print rules/geometry; all 16 original fixtures pass the unchanged numerical oracle. PDF output and revision semantics are unchanged. The successor records the final P5-09 decision, full regression baseline and remaining deployment-font/photo/wrapped-line qualifications. Historical failures below are preserved, not waived.

Original readiness checkpoint: [native corpus and measured results](p5-09-readiness/README.md#measured-corpus-and-results). Three bounded CSS/export/margin corrections restored the intended template/physical-page rules. **10/16 passed; six long-document fixtures failed materially, keeping G-CV-RENDER open and P5-09 NO-GO at that checkpoint.** The successor above supplies the bounded repair. Native acquisition alone is never fidelity passing; broader qualifications and output truth remain explicit.

The renderer is shared, but preview is not a byte-for-byte PDF rendering. The old `CvBuilderEditor.previewDocumentHtml` estimated padding/breaks and cropped server HTML; the successor's `cvPreview.ts` uses native column fragmentation with the existing print rules and measured physical geometry. `CvCustomizeTab`, normalized settings and `ThemedCvRenderer` still influence layout. P4-03 proved keyboard access; the successor supplies the distinct numerical geometry/page-membership proof.

Before P5-09–14, obtain a dedicated rendering checkpoint, with corrections separately authorized if needed:

- Inventory actual saved template IDs/capabilities and supported control combinations. Retain every current template, including Code, plus unsupported-setting normalization and old saved settings.
- Agree expected A4/Letter page geometry, supported margin extremes, header/sidebar/column behavior, section gaps and overflow indications. Compare the same persisted settings/source revision in live preview and actual downloaded PDF, not just page count.
- Render one/long multi-page EN and NB CVs with long headings, section/item hiding, grid/bubbles, columns, photo, dates, page density and template typography. Cover every template at defaults and a risk-based supported-settings matrix; state exclusions explicitly rather than promise every Cartesian combination.
- Record measured margins/page dimensions, text extraction/searchability and images of every compared page; review page breaks, clipping, missing/duplicated text and blank-page/whitespace anomalies. Validate local fonts/Chromium and separately identify deployed renderer differences.
- Exercise preview delay/out-of-order failure/Retry, undo/reload, public versus private PDF and B03 busy/cancel/recovery. Opening tabs or previews must not bypass shared PDF admission.

This is where the reported incorrect margins/templates must be understood and corrected; **P5-11's UI migration is not a substitute for that repair**. Scope expected output before changing geometry. A major rendering replacement is not implicitly authorized.

## Other scoped gates and safe progress

| Gate | Entry condition / scope | Does not block |
|---|---|---|
| G-METRICS | Before P5-06/07: exact source/population/period/sample labels from Phase 3; browser tests for transformations, all five owner visibility flags and error vs zero. [P5-06](p5-06/README.md) supplies Dashboard presentation proof; [P5-07](p5-07/README.md) supplies native Analytics values, period/Back, supported query links and independent error evidence | Shell, Jobs |
| G-WORKSPACE | [P5-08b readiness](p5-08b-readiness/README.md) proves retained queries/history, existing next-task/disclosure destinations, labelled tab/panel relationships and unique accordion IDs; inherited draft/AI guards remain. **Connor's 2026-10-07 decision:** preserve `followMode` as compatibility metadata and defer its absent mode-specific UI to the mail phase. Mode activation is not claimed or a P5-08b prerequisite | Table, independent charts |
| G-CV-BEHAVIOR | Before each CV slice: source/reset/item override, browser history restore, reorder alternatives, save failure and AI accept/reject regression required by its PRES rows, in addition to G-CV-REV/RENDER | Non-editor pages; planning/fixture specification may proceed |
| G-RELEASE | F04 deployed peer/listeners/ports/firewall/NAT/IPv6/DNS/TLS/restarts; production CI/browser runner, providers, backup/restore/rollback and relevant billing/configuration evidence | Local feature-branch UI planning/testing; never grants production approval |

Career Profile, CV library, full Documents/Notifications, mail, Settings and Admin page migrations remain Phase 7. New dashboard layout customization remains Phase 8. No global document/AI/admin/notification producer is invented to complete navigation. If CV gates remain open, finish independent representative slices and report partial/conditional Phase 5 acceptance with CV explicitly deferred; do not claim the full representative set was implemented.