38686-vm/docs/plans/2026-05-16-salary-autoscope-picker-design.md

Salary Auto-Scope Picker — Design

Date: 16 May 2026 Status: Approved by Konrad on 16 May 2026; ready for implementation plan. Branch: ai-dev, on top of the paused, un-pushed Manager/Salaried

• pay-type-filter commits (HEAD 0d77d72). Same logical feature line. NOT to be pushed/deployed until Konrad confirms it works locally — rides the same HARD STOP as the rest of the paused work; ships in one bundled push, Konrad's call.

Goal (one sentence)

When the Add-Adjustment modal's adjustment type is set to Salary, automatically scope the worker picker to managers only — set the pay-type filter to "Managers only", hide daily-worker rows, and untick any daily worker that was already selected — so a Salary adjustment can never silently be created for a daily worker.

Why

Salary is the manager / fixed-pay adjustment type. CLAUDE.md is explicit: Salary is only for Worker(pay_type='fixed'); a daily worker must never receive a Salary adjustment, and "accuracy is critical" for this payroll system. The pay-type filter shipped in the previous task only hides rows — a daily worker ticked before switching the type to Salary would stay checked-but-hidden and POST a bad Salary adjustment. Auto-unticking non-managers on entry to Salary closes that hole at the UI.

Decision (from the brainstorm)

Konrad chose "Filter + auto-untick" over plain display-only filter (B) and over a hard lock (C). Rationale: it removes the silent mis-payment footgun without locking the UI; a deliberate manual override (switch filter back to "All", re-tick a daily worker) is still possible — a conscious act, consistent with the reversible, display-only philosophy of the rest of the pay-type filter.

Behaviour (single rule, both directions)

• Type → Salary:
  1. addAdjPayTypeFilter.value = 'fixed'.
  2. For every .add-adj-worker checkbox: read its .form-check wrapper's data-pay-type. If it is not 'fixed' → hide the row (style.display = 'none') and uncheck it (cb.checked = false). If it is 'fixed' → show the row (style.display = ''); leave its checked state untouched (a pre-ticked manager stays ticked).
  3. Call the existing updateWorkerCount() so the "X worker(s) selected" counter reflects any auto-untick.
• Type → anything else (Bonus / Deduction / New Loan / …):
  1. addAdjPayTypeFilter.value = ''.
  2. Show every row (style.display = '').
  3. Do not alter any checkbox state — daily workers that Salary auto-unticked are not auto-re-ticked. The user re-selects deliberately. (No hidden "remember what I unticked" state — keeps the behaviour predictable.)

Where it hooks (DRY — one chokepoint)

toggleProjectField() in core/templates/core/payroll_dashboard.html is the single function that already runs on:

• every manual #addAdjType change (bound listener),
• init (called once at setup),
• the Pay Salary button (paySalaryBtn sets addAdjType.value='Salary' then calls toggleProjectField()),
• the header-open reset (sets addAdjType.value='Bonus' then calls toggleProjectField()).

Add the filter+untick sync logic at the end of toggleProjectField() (or as a small helper invoked there). This makes all four paths correct with zero new event wiring.

One extra line for the Pay Salary path

The show.bs.modal reset (commit 18ec393, lines ~2089–2100) runs after the Pay-Salary button's pre-show toggleProjectField() call and resets the pay-type filter to '' + shows all rows, then early-returns on _paySalaryOpen (lines ~2105–2108) before any re-apply. So the managers-only scope set by the button would be wiped.

Fix: in the _paySalaryOpen branch, call toggleProjectField() once before return. addAdjType.value is already 'Salary' there, so this idempotently re-applies the managers-only filter+untick and re-affirms the project / Pay-Immediately visibility that toggleProjectField() already manages. No behavioural change for that branch beyond restoring the intended scope.

The _quickAdjustOpen branch is left untouched: quick-adjust never selects Salary, and the reset block already leaves it all-visible — adding a call there is unnecessary and risks regressing the 18ec393 quick-adjust-visibility fix. YAGNI.

Known, accepted boundary

While type = Salary, the user can still manually switch the pay-type <select> back to "All": the existing #addAdjPayTypeFilter change handler reveals the daily rows again (unticked, because Salary cleared them). Manually re-ticking a daily worker and submitting a Salary for them is then a deliberate act, not an accident. This is the explicit consequence of choosing "filter + auto-untick" over "lock" — the silent footgun is removed; a conscious override is not hard-blocked. Documented here so it is a known design boundary, not a latent bug.

Edge cases

Scenario	Result
Open (header) → Bonus, tick a daily worker, switch to Salary	Daily rows hide, that tick clears, counter decrements, filter shows "Managers only".
Pre-ticked manager, switch to Salary	Manager row stays visible & ticked.
Salary → Bonus	All rows reappear; nothing re-ticked; filter back to "All".
Pay Salary button	Modal opens type=Salary, filter="Managers only", only managers visible (re-applied after the show.bs.modal reset).
Quick-adjust button	Unchanged — pre-checked worker visible (type is non-Salary; 18ec393 behaviour preserved).
Manual filter→"All" while type=Salary	Daily rows reappear unticked (accepted boundary above).

Testing

This is pure client-side JS with no view / server / template-data surface, so — exactly like the Task 3 toggle — it is verified by Konrad's manual local checklist, not a Django unit test (the Task 3 plan established and documented this precedent). The automated regression gate is the full suite staying 207/207 OK (the JS addition must not break template rendering).

Manual checklist additions (append to verification):

1. Header-open → Bonus, all workers shown. Tick a daily worker. Switch type → Salary: daily rows hide, the daily tick clears, counter updates, pay-type select reads "Managers only".
2. Tick a manager, switch Salary → Bonus: all rows reappear, the manager stays ticked, pay-type select back to "All pay types".
3. Click Pay Salary: modal opens with type=Salary, only managers listed, pay-type select = "Managers only".
4. While type=Salary, manually set the pay-type select to "All pay types": daily rows reappear and are unticked.

Files touched

File	Change
core/templates/core/payroll_dashboard.html	Extend toggleProjectField() with the Salary filter+untick sync (~25–40 LOC); add 1 toggleProjectField() call in the _paySalaryOpen branch before return
docs/plans/parked-work.md	One line: the paused entry now also covers the Salary auto-scope behaviour
CLAUDE.md	One line under "Manager / Salaried pay": type=Salary auto-applies Managers-only filter + unticks non-managers (UI guard for the Salary=fixed invariant)

No model / migration / view / URL / dependency changes.

Out of scope (deliberately)

• No hard lock / disabling of the pay-type <select> (option C — not chosen).
• No server-side enforcement that Salary targets only pay_type='fixed' (that is a separate, larger hardening; this design is a UI safety improvement only — the existing server behaviour is unchanged).
• No "remember and restore the daily workers I auto-unticked" feature (rejected as hidden state; YAGNI).
• No change to the _quickAdjustOpen path.

Branch / deploy

Build on ai-dev on top of 0d77d72. Do NOT push or deploy until Konrad has run the local verification and explicitly approves. Ships bundled with the rest of the paused Manager/Salaried + pay-type-filter work in a single push, Konrad's call.