jobtrackingapp/docs/redesign/phase-2/TRACEABILITY.md

# Redesign traceability

CV preview successor: [P5-11 chrome/rendering trace](../phase-5/p5-11/README.md#preservation-mapping-and-changed-owners) maps C06/C08/C09/C10/C12 and E08/E09 to settled count/automatic fit, retained document/scroll, named editor return and theme-aware preview chrome. Four unit and two native browser cases supplement the unchanged source/history/AI/frozen boundaries; sixteen renderer HTML hashes and 36 aligned preview/PDF pages remain unchanged. [Visual/keyboard evidence](../phase-5/p5-11/README.md#visual-accessibility-and-performance-evidence) records both locales/themes and viewport qualifications. Human screen-reader, incomplete contrast checks, broader pointer/reflow/font/photo and F04 remain open. P5-12 has not begun.

CV Content predecessor: [P5-10 scoped editing/source trace](../phase-5/p5-10/README.md#change-impact-contract) maps C01/C02/C05–C12, W05/W07 and E07–E09 to explicit source/CV-only descriptions, independent field reset, omitted-entry editing and confirmed add/delete/reorder focus. Four unit and four native locale/theme journeys supplement existing source/history/frozen-package boundaries; the original sixteen renderer HTML outputs and 36 aligned preview/PDF pages remain unchanged. Settings history is not a historical Career Profile snapshot. Human screen-reader, incomplete checks, pointer/reflow/font/photo qualification and F04 remain open; P5-11 had not begun at that checkpoint.

CV frame/navigation successor: [P5-09 scoped frame trace](../phase-5/p5-09/README.md#approved-change-and-preservation-mapping) maps C05–C10, W05 and E07–E09 to the existing editor owner, Content-first studio, named section navigation, pane entry, visible save/version state and native actions. C01/C02, C11/C12 and W07 remain source/AI/export/frozen regression boundaries. The implementation record owns executed results and visual evidence; historical readiness findings below are retained. Human screen-reader acceptance, F04 and production font/photo qualification remain open.

Pagination successor: [P5-09 pagination-fidelity trace](../phase-5/p5-09-pagination-readiness/README.md#preservation-and-changed-owners) preserves C01/C02/C06–C12, W05/W07 and E05/E08/E09 through unchanged source/revision/export owners, native screen fragmentation, deterministic readiness and the original 16-fixture PDF oracle. The former six failures now pass the same tolerances. Human screen-reader, F04 and broader font/photo/fragment qualification remain separately recorded.

CV readiness: [P5-09 integrity/fidelity trace](../phase-5/p5-09-readiness/README.md#regression-and-preservation-trace) maps C01/C02/C05–C12, W05/W07 and E05/E08/E09 to the existing canonical/lens/history/frozen boundaries, server expected-version/atomic comparison, recoverable editor state and native PDF measurements. Five backend, four editor and three native cases supplement the inherited evidence. G-CV-REV passes locally; six material multi-page fidelity failures keep G-CV-RENDER open and P5-09 NO-GO. Historical ledger gaps below are not erased; human screen-reader and F04 remain open.

Job section migration: [P5-08b implementation trace and evidence](../phase-5/p5-08b/README.md#preservation-impact-and-discovered-owners) maps W01–W12, C/M relationships, E07–E09 and Jobs return entries to seven URL-backed sections, existing domain owners, focused unit/native browser tests and synthetic rendered evidence. Frozen/native package proof is retained, personal Notes stays separate from application answers, and `followMode` remains metadata only. No revision, mail or backend semantics are rewritten; manual screen-reader acceptance remains open for P5-15.

Job workspace readiness: [P5-08b native/navigation/accessibility proof](../phase-5/p5-08b-readiness/README.md#preservation-traceability-and-changed-files) supplements W01/W04–W08, C01/C05/C07/C10 and E07–E09 with real SQLite/ZIP and four native locale/theme navigation cases. Historical P2-D01 rows below retain the original expected-failure evidence; the successor owns the repair/results. Connor explicitly deferred absent `followMode` UI to the mail phase while preserving metadata; manual screen-reader acceptance remains open.

Job header/Overview: [P5-08a scoped inventory, preservation and evidence](../phase-5/p5-08a/README.md#preservation-impact-before-implementation) maps PRES-W01/W02/W03 entry, W04/W08/W11 links, J05/J06/J07/J09 entry and E07–E09 to the existing owner, semantic header/summary, progress keyboard access, five new unit cases and two local-browser cases. Deeper W05–W10/W12 owners remain regression dependencies; native package proof, incomplete accordion/contrast checks and manual screen-reader acceptance remain open.

Existing reports destination: [P5-07 inventory, scoped trace and evidence](../phase-5/p5-07/README.md#preservation-and-implementation-decision) maps PRES-S01/S02, E07–E09 and J05/J09 to the shared report owner, authenticated Analytics entry, period/query preservation and existing drill-downs. Dashboard flags/reports remain available; new routes do not imply new metric/provider/production acceptance.

Personal Dashboard: [P5-06 scoped trace, metric definitions and rendered evidence](../phase-5/p5-06/README.md#design-and-preservation-plan) maps PRES-S01/S02, E07–E09, W11/W12 and J05/J09 to retained report/preference/navigation behavior, eight unit regressions and two real-application browser cases. Exact values, independent failures and owner switching have scoped evidence; manual screen-reader acceptance and production evidence remain open.

Current Jobs integration: [P5-04b scoped trace and evidence](../phase-5/p5-04b/README.md#preservation-traceability) maps PRES-J03–J07, W01/W02, E07–E09 and S03 to the shared workspace, compatibility adapter, native/unit regressions and rendered evidence. Its containing commit identifies the implementation checkpoint; earlier phase records below remain historical evidence.

Phase 5 planning: [57-contract change impact](../phase-5/PRESERVATION_IMPACT.md), [navigation migration](../phase-5/NAVIGATION_MIGRATION.md) and [visual evidence protocol](../phase-5/VISUAL_ACCEPTANCE.md). The successor [P5-00 readiness trace](../phase-5/p5-00/README.md#preservation-trace) records bounded shell prerequisite changes and actual evidence. P5-01 visible redesign has not begun; baseline, package/CV and production conditions remain explicit.

Successor planning checkpoint: [Phase 3 impact matrix and architecture](../phase-3/PRESERVATION_IMPACT_MATRIX.md). It maps all 57 contracts to proposed destinations/validation, without changing their requirements or claiming implemented/visual parity. The subsequent [P4-01 trace sheet](../phase-4/p4-01/TRACEABILITY.md), [P4-02 named-control/modal record](../phase-4/p4-02/README.md), [P4-03 preview keyboard record](../phase-4/p4-03/README.md), [P4-04 Settings layout/typography record](../phase-4/p4-04/README.md) and [P4-05 table/list density record](../phase-4/p4-05/README.md) link shared foundation changes to regression and representative visual evidence. [P4-06 acceptance](../phase-4/p4-06/README.md) and its [57-row reconciliation](../phase-4/p4-06/PRESERVATION_ACCEPTANCE.md) retain scoped evidence, incomplete checks and affected-migration gates; they do not claim exhaustive preservation or production readiness.

Phase 2 starts at `2d0f131`. The [preservation matrix](PRESERVATION_MATRIX.md) is the stable baseline: **PRES-E01…PRES-A03**, in the original ledger's groups (not one contiguous numeric range). Old references such as C07 remain valid aliases. Subdivide a later workflow with a suffix, for example `PRES-C07.override-reset`; do not reuse an ID or silently change its meaning.

## Required chain for each later change

`PRES-ID → requirement/source contract → implementation commit + changed owner → regression test + executed result → visual/UX evidence`

The requirement for every current PRES-ID is its **complete original row** in [FUNCTIONALITY_INVENTORY.md](../audit/FUNCTIONALITY_INVENTORY.md), including the source contract. A proposed new requirement uses a separate `NEW-xxx` ID referencing the product brief; it cannot overwrite a PRES requirement. Defects use their original audit IDs or the separate P2-D IDs below, not “preserve the broken behavior.”

For every implementation PR/session, add a row to this file (or link its scoped trace sheet here) with:

| Field | Required evidence |
|---|---|
| PRES-ID / requirement | Original ledger group plus the precise sub-workflow being changed; target-brief requirement if applicable |
| Baseline → destination | Existing route, capture/query/alias/keyboard entry and intended location; preserved/relocated/merged/explicitly deprecated |
| Implementation | Commit SHA, affected components/API owners, reason for the change; “unchanged” is valid but not “done” |
| Automated regression | Named behavioral test, file, command/result and provider/test layer; include negative/dirty/error cases |
| Visual/UX validation | Screenshot/video or review artifact with route, populated/empty/error/locked state, viewport, theme, locale, keyboard/focus result and date |
| Gaps / decision / reviewer | Known baseline defects and intentional missing proof; approval reference only when semantics/deprecation need it |

No screenshot alone proves data preservation. No mocked API test alone proves ownership. No successful localhost run proves F04. A shifted feature remains protected after moving to another page.

## Phase 2 changes (test/CI checkpoint only)

All application implementations and routes remain at their Phase 1 behavior. The commit containing this document identifies the Phase 2 implementation of **regression protection**, not a product migration. Use `git log -- docs/redesign/phase-2` to resolve its SHA without a self-referential commit placeholder.

| PRES IDs → existing requirement | Phase 2 change → automated oracle | Visual/UX evidence |
|---|---|---|
| E07, J04 → command job/company/add entry and reviewed capture | [quick-command-preservation](../../../job-tracker-ui/src/quick-command-preservation.test.tsx): three cases; destinations, callback and no-create boundary | No visual redesign. Native browser keyboard search/add evidence below |
| C11 → per-section review never implicitly applies | [ai-section-assistant](../../../job-tracker-ui/src/ai-section-assistant.test.tsx): reject/close, edit then accept, failed suggestion retry | jsdom interaction only; no model or visual certification |
| C07, C11 → whole-document review changes only accepted CV settings | [cv-builder-deep-link](../../../job-tracker-ui/src/cv-builder-deep-link.test.tsx): apply/reject and invalid/missing/duplicate block responses | jsdom current/proposed comparison; real canonical isolation below |
| W06 → rejected letter does not replace saved content | [application-assets](../../../job-tracker-ui/src/application-assets.test.tsx): reject clears proposal, original remains, no dirty/save | No provider contacted; real delivery remains outside this workflow |
| S03, W11 → scenario-specific rules and retryable preferences | [settings-view](../../../job-tracker-ui/src/settings-view.test.tsx): unchanged scenarios in payload; failed notification save retains draft and retries | Responsive browser preference evidence below |
| C01, C06, C07, C10 → canonical/sibling isolation and responsive editor persistence | [redesign-preservation browser](../../../job-tracker-ui/e2e/redesign-preservation.spec.ts): mobile override, preview/edit, reload, desktop preview; API compares master and sibling before/after | Current Chromium UI at 390×844 and 1440×900, EN/default theme. Behavioral viewport check, not visual approval |
| W01, W05–W08 → source relationships and frozen submission | Same browser spec: fixture creates actual job/CV/letter/file; captures via legacy CV workspace entry | **Expected failure P2-D01:** capture fails on SQLite. Later source-mutation/archive checks not reached; do not mark this migration ready |
| E07, J04, W01 → real command launcher and old links | Same browser spec: Ctrl+K job selection, actual App legacy match link, reviewed add leaves job count unchanged | Current desktop route/keyboard behavior only |
| S03, W11 → responsive rules/notification controls | Same browser spec: edit rule mobile→desktop, save, native API check; notification false survives reload; independent direct rule save | 390×844/1440×900 EN/default theme; no screenshot-based redesign |
| A01, S04, E07 → hidden admin navigation is not authorization; Free AI locks | Same browser spec: hidden admin menu, direct users read/create 403; ordinary CV creation succeeds, all three AI actions disabled, API AI 403 | Current non-admin browser + real API. Admin route shell may render, but cannot retrieve privileged data |
| All 57 → reliable test type baseline | [package script](../../../job-tracker-ui/package.json), [CI gate](../../../.gitea/workflows/ci-deploy.yml): `npm run typecheck` before Jest | Static TypeScript for existing src/app scope; no visual or app change |

## Phase 3 handoff and later migration gates

Phase 3 is **UX architecture documentation**, not a new implementation batch: grouped sidebar/page hierarchy; Jobs table/board view entry; canonical Career Profile versus derived CV/document relationships; full-page versus optional preview; contextual AI review pattern; mobile task flows. Map all 31 existing routes, both aliases, capture/notification/provider entries and all 57 PRES rows to intended destinations.

Keep current MUI/Emotion/React Router/API and ownership contracts while designing. Brand/name/accent and cross-device dashboard customization remain genuine product decisions for the dependent work; do not ask about facts already in the audit.

Before Phase 4/5 code, require an approved route/preservation plan, targeted regression fixtures for that surface's gaps, a shared accessibility/state contract, and coordinated integrity/recovery dependencies. In particular:

- Do not restructure package/tailoring workflows while P2-D01 blocks native success proof.
- Do not conflate B02 identity, stale-CV revision and create-intent idempotency. Those queue items remain distinct; B07 was not started.
- Do not drop mail draft revisions, explicit send/new-attempt controls or owner-bound references.
- Before migrating shared controls, validate EN/NB × light/dark × desktop/mobile, keyboard focus, error/empty/dirty states and representative loaded data. Real screen reader/touch/reflow tests remain manual.
- Do not label a release healthy until the previously failed CI browser runner is diagnosed and the required pipeline passes. F04 requires actual production ingress evidence.

Future trace sheets must link here. The original Phase 2 checkpoint contains **no Phase 3+ implementation commits or visual sign-offs**. Subsequent implementation evidence is linked above and does not overwrite this historical baseline.