jobtrackingapp/docs/cv-redesign/AI.md

CV-UX-AI — contextual writing assistance

Owner-approved addition, 25 October 2026. This checkpoint is part of CV-UX-01 and does not close AI-P5-13 or authorise production activation.

Existing owners and contracts

AiSectionAssistant is already mounted beneath custom content, ordinary section content (including professional summary), and individual entry bullets (experience, projects and education). CvBuilderEditor supplies its existing save-before-generation and reviewed-application callbacks. The new compact actions reuse these callbacks: Improve writing (improve), Suggest content (suggest), Grammar check (grammar), Shorter (shorten). Existing additional actions remain available.

CvVariantController requires local authentication and the existing Pro entitlement on generation/application. CvAiSuggestionService reads the owned variant and Career Profile, checks the requested saved revision/source, validates output shape and grounding, and issues a protected proposal capability bound to owner, variant, version and source fingerprint. Acceptance rechecks that state and uses the ordinary versioned CV save. Neither generation nor acceptance updates the canonical profile. User edits to a proposal are re-evaluated. Generation is not acceptance.

ISummarizerService already routes generation to the self-hosted Python sidecar. Factual review uses /cv/evaluate-rewrite; unavailable or invalid assessments fail closed. No additional provider/model/dependency or model download is introduced. Suggest content uses the selected saved section's career evidence; it does not infer experience from job requirements. Empty fields request substantiated career facts before generation. Cross-section recommendations are not claimed.

The existing cover-letter AiWorkspaceService uses the owned linked CV/profile and job context, returns a reviewable suggestion, and records an AI interaction. The existing Pro/local authorization remains. Its body generation does not have the CV capability/grounding evaluator contract: prompt guardrails and user review are not equivalent to semantic qualification. The four direct controls reuse its existing improve/generate/grammar/shorten operations. Local source changes, source CV changes and cancelled requests invalidate pending proposals. Acceptance edits only the local draft; the ordinary revision-checked letter save remains explicit.

Safety and UX contract

The source prerequisite now refuses letter inference before model invocation or interaction creation unless an owned linked CV resolves actual career evidence. Identity, section headers, an advert and a prior draft are insufficient. Five source/action refusal combinations were added to the full backend suite. The UI maps cover_letter_source_required to actionable EN/Bokmål guidance. The four letter controls are portalled immediately beneath the body field while retaining the existing assistant read lifecycle.

• Original and editable proposed text remain separate; Reject never saves and Accept is explicit.
• Current document language is supplied to CV generation. Letter language uses its existing explicit selector; grammar/improvement/shortening must preserve source language and meaning.
• Loading, retry and logical cancellation retain source text. Cancellation discards responses; it does not claim inference-server interruption.
• Shared controls use MUI and EN/Bokmål strings. Keyboard/mobile/browser checks remain distinct from component tests.
• Source documents and job descriptions are untrusted data, not authority to change instructions or career facts.

Evidence to date (intermediate, not final acceptance)

contextual-ai.trx: 83 backend CV AI tests passed, including four action review/history/canonical-preservation cases. ai-ui.json: 61 combined AI/letter UI tests passed. New direct-action and empty-source tests were observed failing before implementation. The new cover-letter concurrent-edit regression also failed before response invalidation was added. These controlled responses do not demonstrate actual model quality.

Action	Implementation	Frontend	Backend	Actual model / production
Improve writing	Existing CV/letter paths exposed directly	Component pass	CV tests pass; letter regression pending final suite	NOT TESTED / not eligible
Suggest content	New CV action; existing letter generation	Component pass, missing source asks for input	CV tests pass; letter grounding limitation above	NOT TESTED / not eligible
Grammar check	Existing paths exposed directly	Component pass	CV tests pass; letter regression pending final suite	NOT TESTED / not eligible
Shorter	Existing paths exposed directly	Component pass	CV tests pass; letter regression pending final suite	NOT TESTED / not eligible

Outstanding: fresh full regression, endpoint authorization/browser coverage, actual approved self-hosted EN/Bokmål inference and adversarial semantic acceptance, source-grounding qualification for letter operations, human accessibility and language review. Production remains NO-GO; no deferred P5-13 operation is activated by this UI work.