docs: audit pre-phase10 UX architecture and gates

2026-10-27 07:19:58 +01:00
parent 4a8c907d70
commit 5d4b8f23ce
3 changed files with 107 additions and 0 deletions
@@ -0,0 +1,45 @@
 # PRE-P10-UX design and scope
 27 October 2026. Owner specification: CV-QA Addendum/PRE-P10-UX and appended administrator attribution/failure-diagnostics requirements, supplied in the attachment `03bb825f-4d45-40ea-8574-548831f24611/Pasted text.txt`.
 The owner explicitly authorises autonomous safe implementation, validation, commits and pushes in the stated sequence. Routine design choices below are engineering decisions under that authorisation, not a claim that the owner separately reviewed this document. No additional design approval loop is required. Production, main merge, live-model activation and original Phase10 cleanup remain excluded.
 ## Verified entry
 The completed CV-QA baseline is `4a8c907d70cbed235728f7d690b5409e72b93abe`, with remote equality verified. Its conditional acceptance permits development/QA; extraction, human/device/print and production qualifications remain limited. It contains `ef425c2` and CV-UX `4a0af62`. An attached managed worktree isolates unrelated local Docker/tooling/security work. Corrective branch: `codex/cv-builder-blank-undo`.
 ## A: blank creation and interactive history
 Root causes found in source: `sections=[]` means inherit defaults on both server resolver and editor hydration; contact is always inherited; document AI/application matching also treat absent rows as visible. Undo mutates history inside React state updater callbacks, contains settings but not the document name, and has no document-level keyboard handling. Runtime reproduction and failing tests must precede fixes.
 Use nullable settings-JSON flags `sectionsExplicit` and `includeProfileContact`. Missing flags retain legacy behavior and serialization/no-op compatibility. Blank explicitly selects zero sections and suppresses inherited contact/header/photo. Manual custom sections remain CV-specific content; adding existing Career Profile content is a deliberate action. From Career Profile exposes actual available-section/contact choices. A template changes presentation; duplicate preserves content and flags. Every resolver/context consumer must use the same inclusion semantics. Empty resolved content receives clear export validation before PDF allocation; no fictional placeholders are inserted.
 Alternatives rejected: changing the meaning of every existing empty list would rewrite old CVs; hiding seeded defaults only in the UI would leave render/AI/matching leaks. A new master-profile or revision store is unnecessary.
 Interactive undo/redo uses immutable document snapshots, pure state updates and bounded session-only stacks. Text editing groups by focus/edit burst; structural/design actions are individual transactions. New edits discard redo. Autosave uses the existing queue and expected server revision; success is acknowledged only after durable save. Conflict reload/restore/new-document hydration deliberately resets session history, while ordinary saves preserve it. Native input/contenteditable undo remains native; document shortcuts operate outside editable controls. History cannot cross document IDs, and delayed saves/previews must not rehydrate another document.
 ## B: versioned template quality and optional photographs
 Keep all nine existing IDs for compatibility; this is the justified alternative to a numerical6–8 target. The catalogue already spans the requested layout families. Improve actual distinctness/spacing rather than add near-duplicates. Audit short/medium/long/dense equivalents across all nine, render PDF page images and inspect them.
 Known source defects/limits: sidebar CSS ignores configured sidebar palette; Technical's usable identity width is30mm after padding, causing aggressive word wrapping; conservative section keep-together rules can produce sparse pages. Measure before changing shared pagination. Introduce an opt-in design revision if new styling would alter legacy lens renders; missing revision stays legacy. New creation/explicit template Apply may opt into revised styling. Duplicate/restore retain the chosen revision; frozen stored HTML/bytes remain untouched. Reuse licensed embedded fonts and existing photo upload/storage/crop pipeline; add accessible crop alternatives and explicit CV entry points where needed. No generated portraits or second image store.
 ## C: interactive dashboard
 Replace form-heavy arrangement with an edit mode on the actual widgets: drag handles, resizing, accessible visibility/catalogue controls, save/discard/reset, keyboard movement/resizing and status announcements. Keep widget data/actions and the existing preference hook/owner/revision contract. Assess the current official React-Grid-Layout API/licence/React compatibility/bundle cost before selecting it; avoid reimplementing a collision engine without evidence.
 Schema v2 stays in existing preference JSON/revision columns. Deterministic migration preserves v1 stored order, size and visibility; no automatic reset or write on viewport change. Persist bounded geometry with responsive behavior and per-widget minima; retain hidden geometry and future-widget rules. Old-schema clients cannot overwrite newer stored layout data. Phone/touch interactions preserve scrolling and functional widget controls; drag is never the only authoring method. No dashboard SQL migration is needed.
 ## D: administrator processing monitor
 Reuse real `UserOperation`, queue/leases, CV runs and actual task-specific job-subject decoding. Current rows provide latest state, not historical transitions. Add a bounded owned operation-event table with monotonic cursor, UTC time, attempt and allowlisted event/status/stage/error codes. Append only successful transitions atomically; do not save unrelated tracked entities or log every heartbeat. Do not invent history for old rows. Include additive migration, retention, account erasure/export and actual MariaDB tests.
 Dedicated server-admin-authorised list/detail/event APIs project safe metadata. Existing admin audit permits cross-owner identity/job metadata; ordinary APIs remain owner-scoped. Every association is checked against the operation owner. Display original user ID plus current permitted name/email; CV imports show no linked application, safe retained file metadata and known page count only. Deleted/mismatched relationships remain unavailable. No existing user-detail route is assumed.
 Use bounded cursor polling with pause/resume/reconnect, filters, pagination and finite retention; SSE is optional, not required infrastructure. No raw document/prompt/completion/request/exception/stack/connection/lease data enters events or responses. Sanitisation occurs before storage/transmission. Unknown failures remain unknown. Operation GUID is the correlation key; propagate safe correlation across actual worker/backend/sidecar boundaries. Read-only monitoring avoids new privileged cancellation/retry paths unless separately proven safe. Audit any sensitive administrative action through existing owners. Disabled/disconnected model assistance is shown honestly; no live inference is started.
 ## Publication, preservation and acceptance
 After validated A, create `feature/cv-template-library-review` from accepted A; then `feature/dashboard-interactive-grid` from accepted B; then `feature/admin-processing-monitor` from accepted C. Consolidate on `test/pre-phase10-ux-acceptance` from accepted D. No disconnected branch omits earlier work. Each checkpoint has focused RED/GREEN evidence, review, documentation, commit/push and remote check. Final regression serialises native build/browser/provider lanes and retains independent counts/source/runtime identities.
 Preserve all57 capability groups/33 routes, canonical Career Profile, overrides, document/history/letter/application revisions, ownership/authentication, v1 dashboard data and licensed physical rendering. Keep old evidence/goldens; if intentional new design output differs, use separate versioned specimens rather than conceal regressions. Human/device/native-language/print/live-model/deployed acceptance is only recorded when actually performed. Final independent verdicts cover all requested areas, with owner actions and Phase10-vs-production scopes. Stop after the new Phase10 handoff; do not start cleanup.
@@ -0,0 +1,19 @@
 # Owner feedback and acceptance register
 27 October 2026. Baseline4a8c907. Entries are requested work, not passing claims.
 | ID | Owner requirement | Entry evidence / intended verification | State |
 |---|---|---|---|
 | A1 | Truly blank CV, zero content sections/header facts, no fictional defaults | Both resolver/editor inherit empty arrays; contact always hydrates. Tests must cover persistence/design/copy/restore and no AI/matching leakage. | Source defect confirmed; runtime reproduction pending |
 | A2 | Trustworthy undo/redo and native shortcuts | Settings-only stacks mutate inside state updater callbacks; Strict Mode and autosave/document-switch tests required. | Investigation |
 | B1 | Audit every template and fix spacing/alignment/page flow | Nine current IDs; sidebar palette ignored, narrow identity geometry and conservative packing identified. Actual per-template rendering pending. | Audit prepared |
 | B2 | Six–eight distinct quality styles or justified count | Retain9 existing IDs for compatibility; improve identities rather than add duplicates. Need actual visual proof. | Engineering count decision; qualification pending |
 | B3 | Optional secure portrait/upload/crop/preview/remove/PDF | Existing shared avatar/crop/storage pipeline; keyboard crop controls absent. | Reuse identified; new acceptance pending |
 | C1 | Direct draggable/resizable dashboard with catalogue/reset/view/edit | Existing v1 order/standard/full preferences and revision-safe hook; no arbitrary geometry. | Audit prepared |
 | C2 | Preserve responsive/hidden/old/concurrent preferences | v2 migration and no viewport-triggered writes/reset; real pointer/keyboard/provider tests required. | Pending |
 | D1 | Admin-only actual processing task/status/stage/stats/filter view | Existing UserOperation latest rows; admin identity precedent; no user detail route. | Audit prepared |
 | D2 | Safe live event viewer, bounded retained actual history | No durable operation history; retries wipe current-state diagnostics. Add atomic typed events and cursor polling, never raw logs. | Pending |
 | D3 | User attribution, actual job/import linkage, failure detail/correlation | Operation GUID/owner immutable; subject decoders differ; CV run has no job association. Safe identity/file/error policies and missing/deleted cases required. | Pending |
 | INT | Full preservation and independent acceptance | Inherit57 groups/33 routes and all prior qualifications. No production/main/live-model/cleanup work. | Pending |
 Original CV-QA/CV-UX acceptance records remain historical. Current final verdicts will be issued only from actual evidence; no owner-approved exception to A1/A2 has been requested or inferred.
@@ -0,0 +1,43 @@
 # PRE-P10-UX implementation plan
 > **For agentic workers:** Use superpowers:executing-plans or subagent-driven-development. Root owns integration, Editor history, serial native evidence and Git. Scoped workers own assigned files only; preserve other edits. Steps use checkbox syntax.
 **Goal:** Deliver correct blank/history authoring, qualified distinct template designs, direct dashboard arrangement and a safe administrator processing/event monitor before cleanup.
 **Architecture:** Extend existing settings/renderer, canonical preference/revision and durable operation owners. No duplicate master profile, image store or queue.
 **Tech Stack:** Existing .NET9/EF/Pomelo/MariaDB, React19/MUI7/TypeScript, Playwright, pinned model-free sidecar/Docling and licensed font/PDF infrastructure.
 **Spec:** Owner addendum and DESIGN.md.
 ## Global constraints
 No main merge, production service/database/storage/model/cache/deployment operation, destructive migration, live inference, FINN/NAV/LinkedIn initiative or Phase10 cleanup. All feature branches cumulatively contain4a8c907. Use safe synthetic fixtures, isolated resources and exact independent counts. Commit/push/verify every validated checkpoint. No false human/device/model acceptance.
 ## Review focus
 - Explicit empty must survive normalize/save/reopen/design/apply/duplicate/restore and cannot leak master facts into AI/matching.
 - Strict Mode, native typing undo, burst grouping, in-flight autosave, stale revisions and document switches cannot corrupt history or save another document.
 - New template spacing must not alter legacy/frozen output; genuine content completeness and actual physical pages outrank compact page counts.
 - v1 preferences, hidden/future widgets and breakpoint changes must survive v2 geometry without automatic resets or lost concurrent updates.
 - Admin joins, failure data and event transactions must fail closed without storing sensitive content, exposing foreign ordinary-user APIs or manufacturing missing history/model jobs.
 ## Checkpoints
 - [x] P10-UX-00: read owner specification, verify latest CV-QA ancestry/remote/entry, isolate managed worktree, audit four owners and choose compatibility-first design. Create feedback register and branch plan.
 - [ ] A-01: reproduce blank hydration/header/export and Strict Mode history failures in focused tests plus actual local development browser. Save RED evidence; no application fix before reproduction.
 - [ ] A-02: nullable explicit inclusion flags across resolver/editor/AI/matcher, deliberate creation/profile selection, empty export validation; pure immutable grouped session history/shortcuts/epoch guards; focused unit/provider/browser and RD21 checks, review, docs, commit/push/verify.
 - [ ] B-00: branch from accepted A; inventory9 IDs, render equivalent short/medium/long/dense samples, establish measured spacing/pagination defects and legacy source/PDF proof.
 - [ ] B-01: opt-in revised design semantics and template-specific spacing/palette/identity fixes; portrait controls reuse secure existing storage/crop with keyboard alternatives; tests and per-template Windows/Linux visual evidence; commit/push/verify.
 - [ ] C-00: branch from accepted B; verify official grid API/licence/compatibility/bundle, define v2 JSON and v1 migration tests.
 - [ ] C-01: interactive real widget grid/edit/catalogue with geometry, min sizes, keyboard/touch alternatives, conflict-safe persistence; unit/provider/drag/resize/reflow/browser coverage; commit/push/verify.
 - [ ] D-00: branch from accepted C; define exact safe diagnostic/event schema and admin identity/association policies; tests first.
 - [ ] D-01: atomic structured events/correlation/retention and account rights, safe admin list/stats/detail/events, polling filters/reconnect/pause, EN/Bokmål and responsive UI; security/provider/browser validation; commit/push/verify.
 - [ ] UX-INT-00: branch `test/pre-phase10-ux-acceptance` from accepted D. Fresh full backend/frontend/ordinary and added browsers/real MariaDB/RD21/Python/Docling/import/contracts/security/type/lint/build/Windows/Linux PDF/preservation; exact source/discovery/native exits, retain failures and fix regressions.
 - [ ] UX-INT-01: independent feature/overall/Phase10/production verdicts, all57/33 preservation carry-forward, accepted branch commit register, human/operator debt and cleanup-only handoff. Commit/push/remote equality/own-work clean; preserve unrelated primary checkout work; stop.
 ## Execution commands and ownership
 Use repository SDK `C:/Users/Connor/.dotnet/dotnet.exe`, existing npm/Jest/Playwright configs, `scripts/mariadb-integration.py`, unchanged original PDF proof helper and model-free sidecar. Native build/browser/provider lanes remain serial; unit-only Node may run independently. Graph-first where a local graph exists, followed by AST-only updates after code changes. New worktree dependencies are installed offline from cached lock files, without touching primary node_modules.
 Root owns `CvBuilderEditor.tsx` and Editor history tests; A worker may own settings/resolver/creation/matching/export and library/types/tests/translation additions after explicit assignment. Template and dashboard/admin audits are read-only until preceding feature entry gates pass. Later file ownership will be recorded at dispatch.