Scoring

Scoring compares Discovery's canonical, evidence-linked employer analysis with a versioned Candidate Profile. It produces an applicant-side fit score, confidence, blockers, gaps, and requirement-level evidence for your own triage. Discovery owns how the employer analysis is generated and which perspectives participate; this page owns how that accepted input becomes a fit decision. For a shorter conceptual introduction, read Evidence-based Job Fit Scoring.

Before a new scoring attempt, JobCtrl reuses a posting observation or a trustworthy, source-bound canonical capture from the last six hours. Missing, changed or older evidence uses the normal availability check. Usable content can proceed while availability stays unknown; confirmed unavailable postings stop new provider work while preserving the accepted score and evidence. Use Job Detail’s Check availability to retry; see saved posting availability.

How The Score Is Calculated

JobCtrl does not ask a model for one opaque number and save it. The model classifies the evidence for each posting requirement; versioned, deterministic code turns those classifications into the persisted 1–10 score.

Each distinct saved job has its own assessment and recorded evidence, even if another job has similar posting text. Repeating an unchanged assessment for the same job can reuse its recorded decision; scoring a different job can require another model call.

When Discovery supplies explicit requirements, the calculation works like this:

1. Send the accepted requirements to the scorer. The scoring request includes each requirement's ID, posting text and evidence, priority weight from 0 to 1, and tier: must-have or nice-to-have. The structured scorer returns those fields with its assessment.

2. Classify the returned evidence. A matched or transferable row must carry at least one supplied Candidate Profile evidence ID. Strict determination validation rejects foreign requirement/evidence IDs and unsupported quotes. Scoring joins each requirement to its recorded scope in the accepted job interpretation, retaining the determination ID with its contribution. It does not infer scope from wording. Inspect the evidence links, and treat any Unavailable evidence label as a reason to correct or re-score.

3. Apply evidence credit and requirement priority. The current requirement-fit-v2-scoped formula uses these values for requirements whose recorded scope is resume (candidate capabilities):

   Evidence classification	Credit
   Direct match	100%
   Strong match	85%
   Transferable evidence	60%
   Missing, blocked, or not assessed	0%

   Eligibility, logistics and employer conditions remain assessed and visible, with zero contribution to both the numerator and denominator. Their unmet or unconfirmed status does not lower capability fit. Eligibility warnings and hard blockers still control downstream readiness separately.

   A must-have capability requirement counts 1.25× its saved weight; a nice-to-have counts 1.0×. JobCtrl then calculates weighted coverage and maps it to the 1–10 scale:

   adjusted weight = requirement weight × tier multiplier
   coverage = sum(adjusted weight × evidence credit) / sum(adjusted weight)
   score = 1 + round(9 × coverage)

   Each row's adjusted weight and awarded points are rounded to four decimal places before JobCtrl totals them.

   Rounding is to the nearest whole number, with halves rounded up, and the result is limited to 1–10. If a capability requirement is classified as blocked, the final score is capped at 4 after the weighted calculation.

4. Assign the display band. Scores 9–10 are Excellent, 7–8 Strong, 5–6 Plausible, 3–4 Stretch, and 1–2 Poor.

Missing or foreign scope bindings, an unrecorded interpretation source, or a posting with no weighted capability requirements cannot create a replacement score. Failed refreshes preserve the accepted score. Historical requirement-fit-v1 reports keep their original calculation until an explicit successful rescore; that earlier formula included every requirement and capped any blocked row.

For example, suppose a must-have with weight 1.0 is a direct match and a nice-to-have with weight 0.5 has transferable evidence:

Requirement	Adjusted weight	Credit	Awarded points
Must-have, direct match	1.25	100%	1.25
Nice-to-have, transferable	0.50	60%	0.30

Coverage is 1.55 / 1.75 = 0.886, so the score is 1 + round(9 × 0.886) = 9: Excellent. The Job Detail requirement report shows the persisted assessment, evidence links, and contribution for every row. Resolved profile evidence is the support you can audit; an unavailable reference is not proof of a match.

Job Detail also shows the saved weighted coverage beside the score, including the recorded blocking requirements and the formula's cap when applicable. This context remains visible while the detail sections are collapsed. It appears only for the matching job and score version; a manual correction keeps its own explanation instead of being attributed to the earlier requirement report.

When Requirement Rows Are Unavailable

The requirement-led formula runs only when the scorer returns at least one valid requirement-assessment row for the current employer-analysis generation. Otherwise JobCtrl uses its versioned compatibility rubric: 45% technical fit, 30% experience fit, and 25% role fit. It takes the weighted average of those three 0–10 values, rounds halves up, clamps the final score to 1–10, and applies the same score bands.

Score, Confidence, And Eligibility Are Different

• Confidence is a review signal, not a points adjustment. Low confidence tells you to inspect the evidence; it does not automatically lower the score.
• Eligibility is recorded separately from soft fit. A blocked requirement caps requirement-led scoring at 4, while hard eligibility blockers can also prevent downstream tailoring. Warnings and eligibility are not added as a generic points penalty.
• Compensation preferences never block tailoring. A posted salary below your preferred range remains visible as an auditable warning, including the parsed amount and source, while the job continues through materials.
• The minimum-fit threshold does not change the saved score. It decides whether an existing score is eligible for materials. Changing it does not call the model or recalculate the score. A below-threshold decision is shown on Tailor, Cover, and Apply as skipped with MIN_SCORE and the exact score/threshold pair; it is not pending work or a generation failure.
• A correction is not a hidden weight change. Your correction creates a new reviewed score version and a calibration anchor. An explicit re-score runs the current policy again against the current canonical inputs.

Indexed Scoring Keywords

Each score version stores its keywords in a normalized, indexed relation keyed by tenant, job, and score version. Historical versions remain auditable, but Jobs filtering and GET /v1/scoring/keywords use only the score version that the current projection renders. The aggregation returns both the canonical normalized key and a display spelling with its score version and job count.

GET /v1/jobs?normalizedScoreKeyword=... accepts the exact canonical key from that aggregation. Normalization is owned by persistence, including Unicode case-folding; clients do not guess or re-normalize display text.

What You Can See And Control

Scoring runs inside Discover preparation. Review it on the current product surfaces rather than looking for a separate scoring page:

• /jobs exposes fit-score filters, sorting, bands, and stage state.
• /jobs/:jobId shows the employer analysis, score breakdown, confidence, hard blockers, matched/missing/transferable signals, requirement-fit report, policy metadata, correction history, and stale state when recorded. Profile evidence attached to a requirement resolves through the Evidence map into its title and a useful source excerpt; unresolved references are labeled unavailable, with the raw storage key kept under Technical details. Each requirement's Show evidence / Hide evidence control operates independently. Every requirement starts expanded, including matched, transferable, missing, blocked, and unassessed requirements. The title, tier, importance, and match status remain visible when collapsed. A new analysis generation resets these defaults; ordinary page updates preserve your open cards. Fit evidence must match the current analysis and requirement. Resume coverage must separately match the requirement recorded when that resume was generated. If that source identity is unavailable or changed, coverage is marked not recorded while the accepted resume remains available.
• /evidence-map works in the opposite direction: it shows where a profile achievement or skill was used by requirement-fit and generated materials.
• /settings owns scoring and target guidance. Guidance influences subsequent scoring work but is not candidate evidence.
• /settings/models selects employer-analysis perspectives. Their execution, failure, and fallback behavior belongs to Discovery.
• /discovery owns the minimum-fit eligibility threshold. Changing that threshold can make persisted scores eligible or ineligible for materials; it does not rewrite the score or call the scoring model again.

From the Job Detail workspace you can record a corrected score with a rationale or ask for an explicit re-score against the current policy. The Jobs toolbar also offers bounded current-policy maintenance for selected or outdated scores. A correction and a re-score are different: correction records your reviewed decision; re-score runs the current scoring pipeline and creates a new model- derived version. If employer analysis changes after the last assessment, Job Detail labels the requirement fit outdated and offers a per-job re-score. The earlier score and accepted materials stay available while the new assessment runs. Jobs with an analysis but no saved requirement assessment are labeled not assessed instead.

The ideal-candidate narrative describes the candidate's capabilities and the role's needs directly. Explanations of expert agreement or how the profile was determined belong in the analysis audit metadata. Generation rejects such process commentary and re-asks before accepting a new record. Old analyses remain readable; a supported analysis refresh replaces invalid prose only after its replacement passes validation, preserving the previous generation on failure.

Low confidence means the evidence needs review, not that the fit is necessarily low. A high score with evidence you cannot personally support is likewise a reason to correct or investigate it.

Scoring priorities

Settings → General → Scoring guidance → Scoring priorities adds user guidance describing what strong-fit jobs should demonstrate. It is consumed by newly started scoring work. It is policy input, not candidate evidence, and it does not rewrite historical score versions.

Target role guidance

Target role guidance adds role or company preferences to newly started scoring work. It supplements the target-search titles owned by Discovery; it does not add, remove, or rename those search targets.

A profile change can start preparation while other jobs are still running. Those jobs keep their current execution; the continuation processes other eligible work. If you cancel or reset a job, the older execution cannot replace its successor's result. A real scoring failure stays visible while accepted results for other jobs remain saved.

Source Of Truth And Ownership

• The posting snapshot owns employer claims. Analysis evidence spans must match the captured posting text after formatting-only normalization. A model paraphrase is not source evidence.
• The Candidate Profile owns candidate claims. Scoring receives an immutable profile snapshot; neither analysis nor scoring can add experience or skills.
• Discovery supplies the canonical requirement reading. It records role framing, requirements, priorities, keywords, posting evidence, canonicalization policy and generation identity. Scoring and Tailoring consume that accepted record; its perspective and recovery rules stay in Discovery.
• Scoring owns the decision record. Versioned job_scores rows hold the resolved score, criteria snapshot, requirement-fit evidence, and non-sensitive trace. scoring_policies owns rubric/policy versions and calibration anchors; stale markers record when an older score awaits deliberate adoption of a newer policy.
• Tailoring owns requirement use, not requirement existence. The accepted analysis and requirement-fit report retain every employer requirement. Tailoring classifies whether each one is resume-coverable or context-only; logistics, eligibility, and employer conditions remain available to fit and Apply Review without becoming resume-coverage failures.
• Operations owns display projections. Jobs reads expose persisted analysis and score evidence. They do not call a model or recompute a score on request.
• Explicit feedback remains history until an owning policy says otherwise. Score corrections and their anchors are auditable inputs, but Apply candidate acquisition does not apply a second feedback-based rank adjustment or let an unaccepted learning recommendation reorder jobs.

The model may extract structured evidence and propose fit. The final persisted decision is resolved through the versioned scoring policy, so a raw model opinion is not the sole authority. Scores are for a job seeker ranking jobs, not for an employer ranking people.

Lifecycle

1. Start with an enriched posting. Scoring only consumes the usable job record and its captured content.
2. Order work. A bounded scoring pool uses recency and stable IDs. Vocabulary overlap does not decide which jobs are scored.
3. Consume the accepted employer analysis. Discovery preparation supplies the evidence-linked requirement reading; scoring does not create a parallel interpretation of the posting.
4. Resolve fit. The scorer combines that analysis, the profile snapshot, user guidance, and current policy into structured fit evidence and a policy- resolved score.
5. Persist and project. The score version, criteria, trace, requirement-fit rows, analysis generation, and events are saved before Jobs and Evidence projections expose them.
6. Correct or evolve deliberately. A user correction creates a new score version and a calibration anchor. A new scoring policy can mark comparable older scores stale, but it does not silently replace them; an explicit re-score adopts the current policy. Resetting stale work keeps the saved score visible and marked stale until a matching replacement is committed. Failed or canceled work, or reuse of the saved score, does not clear the warning. A later policy change remains visible if an older assessment finishes. Reset leaves queued or running scoring alone. Wait for it to finish, then retry the reset if the score is still stale; an already-pending score is ready for scoring. Reset only targets active jobs: hidden, deleted, or inactive postings retain their saved scores and warnings. Unhide or restore a job, or wait until the posting is active again, before retrying its reset. A manual correction also retains any existing warning.
7. Review profile edits on request. Saving your profile does not update scores or regenerate materials. Jobs indicate when your saved score predates the profile. Update score first asks your configured scoring model whether the edits could affect this job. If they are insignificant, the score and original date stay unchanged and the model's reason is available in score controls. Significant edits trigger normal scoring. A failed comparison preserves the saved score and reports the failure; older scores without comparison inputs cannot be declared current. A scoring-policy change separately requires a new assessment.

Implementation And API Pointers

Layer	Pointer
User workflow	Daily Workflow → Review Jobs and Discovery → Employer Analysis Perspectives.
HTTP contract	Jobs list/detail reads, GET /v1/scoring/keywords, POST /v1/jobs/:key/score-correction, per-job current-policy re-score, and bulk/stale-score actions; see Jobs & Materials API and the complete lifecycle contract.
Worker implementation	workers/automation/src/jobctrl/scoring/ (employer_analysis.py, scorer.py) and workers/automation/src/jobctrl/domain/scoring/; canonical analysis gates and persistence live under workers/automation/src/jobctrl/domain/materials/analysis* and workers/automation/src/jobctrl/infrastructure/materials/employer_analysis_repository.py.
Product components	apps/web/src/contexts/scoring/, apps/web/src/contexts/materials/components/EmployerAnalysisPanel.tsx, and the Jobs detail/triage views.
Deep architecture	Scoring, Materials → Canonical Employer Analysis, and Stage Walkthrough → Score.

Semantic Determination Authority

Scoring work limits use recency and stable IDs. The model supplies typed blockers with spans and requirement verdicts bound to canonical IDs; code resolves only weights, caps and bands. Posting constraints, seniority, geography and requirement scope come from the accepted job interpretation. No prose reclassification or lexical retrieval decides eligibility.

See the decision for caching, provenance and failure contracts.

Optional company context

Company briefings add separately dated public context beside Role Analysis. They are explicitly configured and refreshed, shared across confirmed company/job links, and do not change fit scores or posting requirements.

Selected-job demand and learning milestones

Open Selected-job demand and learning milestones on /evidence-map. Name a cohort, choose its selection date, select up to 30 saved jobs and optionally record aspirations. Review selected cohort makes no model call. It shows unique selected identities, descriptions available for analysis, missing descriptions, exact duplicate application-identity groups (shared URL and identical posting content) and usable confirmed achievement sources. Repeated selections and shared recorded application URLs plus exact title/employer/description content count once; duplicates with different identities may remain. The selection date labels your cohort, not the publication dates of its postings.

Compare reviewed postings sends the reviewed descriptions and unique, confirmed, supported/verified achievement evidence to the configured model in the Profile accounting lane. The saved comparison identifies its profile version, source snapshots, verbatim posting and achievement citations, provider/model, prompt/schema versions and determination fingerprint. Counts refer only to distinct analyzed postings in this cohort. Missing evidence means no confirmed support was found in these sources; it does not establish inability or a market-wide skills statistic. Declared skills and aspirations cannot serve as confirmed evidence.

Choose each proposed learning or evidence-building milestone explicitly. Its origin retains the exact cohort revision, comparison, citations, completion criterion and selection time. Save progress and a completion-evidence statement or artifact reference; completion requires a nonempty statement. Status changes retain a revision history. These statements remain user-attested activity, never a readiness score or an automatic skill, Profile, fit, materials or Apply update. Confirm any new achievement through the existing Candidate Profile review flow.

Profile/posting changes mark historical comparisons for review. Refreshing a cohort can change its selected jobs and aspirations; previously chosen milestones retain their original sources and show that the cohort changed. A failed refresh or stale revision preserves the last accepted comparison and your draft. The interface shows up to 20 recent cohorts, 100 milestones and 50 recent activity revisions per milestone; older records remain in local storage. The browser-only demo explains that this capability requires a local workspace.