# Product Requirements Document
# 039 - Task Assignment & Position-Based Completion

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision

Every task in the store is owned by the right person or the right role, with full accountability tracking from assignment through completion — so nothing falls through the cracks and managers know exactly who did what.

### Problem Statement

Today, the BuyerKiosk task list system supports assigning individual tasks to specific employees, but lacks:

1. **Position-based assignment**: Recurring tasks like "Process backstock" naturally belong to a *role* (e.g., Inventory), not a specific person. Currently, managers must manually assign tasks to individuals each day, which is tedious and error-prone.

2. **Group-level assignment**: Entire task groups (e.g., "Closing Procedures") should be assignable to a position or person as a unit. Today, each task must be assigned individually.

3. **Accountability tracking**: When a task assigned to one person or position is completed by someone else, there's no audit trail. Managers can't see if tasks are consistently being done by the wrong people, which may indicate scheduling or training gaps.

4. **Schedule integration**: Managers creating or editing shifts can't see or assign tasks in context. They must switch between the schedule and workbook to coordinate who does what.

5. **Daily assignment workflow**: There's no single view for a manager to see all tasks for the day and assign/reassign them efficiently.

The consequence is wasted manager time on daily task assignment, unclear accountability, and tasks that either don't get done or get done by unqualified staff without anyone knowing.

### Value Proposition

This feature turns the task list from a passive checklist into an active accountability system:

- **Managers save 10-15 minutes daily** by setting position defaults once instead of assigning tasks every day
- **Position-aware completion** ensures qualified employees do the right tasks, with automatic escalation visibility when they don't
- **Shift dialog integration** lets managers plan tasks while they plan the schedule, in one workflow
- **Full audit trail** reveals patterns — which tasks consistently go out-of-position, enabling better training and scheduling decisions

## User Personas

### Primary Persona: Store Manager
- **Demographics:** 25-45, retail management experience, moderate technical comfort, uses BuyerKiosk daily
- **Goals:** Ensure all daily tasks are completed by qualified staff. Minimize time spent on task delegation. Have clear visibility into who did what.
- **Pain Points:** Spends too much time manually assigning recurring tasks. Can't tell if the right people are doing the right tasks. Has to juggle between schedule and task views to coordinate work.

### Secondary Persona: Shift Lead
- **Demographics:** 20-35, frontline team lead, comfortable with mobile apps, may use BuyerKiosk Live app
- **Goals:** Know which tasks are assigned to them or their team. Complete tasks efficiently during their shift. Hand off incomplete work clearly.
- **Pain Points:** Unclear which tasks are "theirs" vs. general. No easy way to see their task load alongside their shift schedule. Sometimes does tasks outside their role but it goes unnoticed.

### Tertiary Persona: Team Member (Task Executor)
- **Demographics:** 18-30, hourly employee, uses kiosk or mobile for clock-in and task completion
- **Goals:** See their assigned tasks clearly. Complete tasks and get credit. Not be blocked from helping even if a task isn't formally "theirs."
- **Pain Points:** Doesn't always know what they should be working on. When they help out by doing someone else's task, there's no acknowledgment or record.

## User Journey Maps

### Journey 1: Manager Sets Up Position-Based Task Assignments (One-Time Config)

1. **Awareness:** Manager notices they're spending time every day assigning the same tasks to whoever is working the Inventory role.
2. **Configuration:** Manager opens the task list admin page, selects the "Backstock" task group, and assigns it to the "Inventory" position. Individual tasks within the group can optionally be overridden.
3. **Verification:** Manager sees the task group card now shows the "Inventory" position badge. Each task inherits the group assignment unless individually overridden.
4. **Outcome:** From now on, the Backstock group automatically appears with the Inventory position badge in the workbook. Any clocked-in employee with the Inventory position can complete those tasks.

### Journey 2: Manager Assigns Tasks via Shift Dialog

1. **Context:** Manager is creating tomorrow's schedule. They click on a shift for "Casey" (Shift Lead, 2pm-10pm closing shift).
2. **Assignment:** In the shift dialog, a "Tasks" section shows unassigned tasks for that day. Position-matching tasks appear first (Shift Lead tasks highlighted). Manager checks off "Closing Procedures" group and two individual tasks.
3. **Result:** Those tasks now show Casey's avatar on the workbook for that day. The position assignment is overridden by the person assignment for that specific date.
4. **Completion:** Casey completes the tasks during her shift. Completions are linked to her shift record.

### Journey 3: Daily Task Assignment View

1. **Access:** Manager opens the Daily Task Assignment view (accessible from both workbook and schedule page).
2. **Overview:** Sees all task groups for today with their current assignments — some show position badges (defaults), some show employee avatars (per-day overrides), some are unassigned.
3. **Bulk Action:** Manager reassigns the "Closing" group from its default "Shift Lead" position to "Casey" specifically for today. Drags "Opening" group to "Jack" who's opening.
4. **Mobile:** Alternatively, the store owner does this from the BuyerKiosk Live app during their morning commute via the mobile API.

### Journey 4: Task Completion with Position Verification

1. **Task Appears:** Team member sees "Process backstock intake" on the workbook, assigned to "Inventory" position (green badge).
2. **Completion Dialog:** Employee clicks to complete. Dialog shows clocked-in employees who have the "Inventory" position.
3. **Happy Path:** Employee selects themselves (they have the Inventory position). Task completes normally. Their qualifying position is recorded.
4. **Out-of-Position Path:** Employee doesn't have the Inventory position. They toggle "Show all employees," select themselves. System shows a warning: "This task requires the Inventory position. Please provide a reason." They enter "Covering for Kay who called out." Task completes with Level 2 out-of-position flag.

### Journey 5: Person-Assigned Task Done by Someone Else

1. **Setup:** Task "Verify safe count" is assigned to Casey for today.
2. **Situation:** Casey had to leave early. Jack (Shift Lead) needs to do it.
3. **Completion:** Jack opens the task, sees "Assigned to: Casey." Clicks complete. Dialog warns: "This task is assigned to Casey. Please provide a reason for completing on their behalf." Jack enters "Casey left early, manager approved."
4. **Audit:** Completion recorded as Level 1 out-of-position (wrong person). Casey still shows as the original assignee. Jack recorded as completer with reason.

### Journey 6: Carryover Task with Stale Assignment

1. **Previous Day:** "Organize storage unit" was assigned to Casey yesterday. She didn't finish it.
2. **Carryover:** Task appears in today's workbook in the red carryover section. Still shows Casey's avatar but with a "stale" visual indicator (faded/dashed border).
3. **Action:** Manager can reassign via the workbook or daily assignment view. Or Casey can complete it today.

## Feature Requirements

### Must Have Features

#### Feature 1: Position Assignment on Tasks
- **User Story:** As a store manager using BuyerKiosk native scheduling, I want to assign a recurring task to one or more positions so that any qualified clocked-in employee can complete it without me assigning it daily.
- **Acceptance Criteria:**
  - [ ] Tasks can be assigned to one or more positions from the store's active `schedulePositions`
  - [ ] Position assignment is optional — tasks can remain unassigned
  - [ ] Tasks with multiple positions show the primary position badge (first by sortOrder) + "+N more" count
  - [ ] Full position list visible on click/tap (popover on desktop, bottom sheet on mobile web)
  - [ ] Position assignment persists across days for recurring tasks (it's the default)
  - [ ] Only available for stores with BuyerKiosk native scheduling active — position UI hidden for WhenIWork/Homebase stores
  - [ ] If an assigned position is deactivated, task retains the assignment but shows a "position inactive" indicator; manager prompted to update

#### Feature 2: Position Assignment on Task Groups
- **User Story:** As a store manager, I want to assign an entire task group to a position so that all tasks in that group default to that position without individual configuration.
- **Acceptance Criteria:**
  - [ ] Task groups can be assigned to one or more positions
  - [ ] Group assignment cascades to all tasks within the group as a default
  - [ ] Individual task assignments override the group-level assignment
  - [ ] UI clearly indicates which tasks inherited group assignment vs. individually assigned
  - [ ] Group assignment configured on the task group card in admin

#### Feature 3: Per-Day Person Assignment
- **User Story:** As a store manager, I want to assign a task or task group to a specific employee for a specific day so that I have clear person accountability.
- **Acceptance Criteria:**
  - [ ] Tasks/groups can be assigned to a specific person for a specific date
  - [ ] Person assignment overrides position assignment for that day only
  - [ ] Next day reverts to the default position assignment
  - [ ] Workbook shows the employee's avatar/initials for person-assigned tasks
  - [ ] Person-assigned tasks still show the position context alongside the person's name

#### Feature 4: Per-Day Group Override
- **User Story:** As a store manager, I want to override a task group's default position assignment for a specific day, reassigning the whole group to a different position or person.
- **Acceptance Criteria:**
  - [ ] Manager can change the group assignment for a specific day
  - [ ] Override applies to all tasks in the group (unless individually overridden)
  - [ ] Override is date-specific — reverts to default the next day
  - [ ] Override clearly indicated in the UI (e.g., "Today: Casey" vs. "Default: Shift Lead")

#### Feature 5: Position-Aware Completion Dialog
- **User Story:** As a team member at a store with BuyerKiosk native scheduling, I want the task completion dialog to show me qualified employees first so I can quickly select the right person.
- **Acceptance Criteria:**
  - [ ] When completing a position-assigned task, dialog initially shows only clocked-in employees with a matching position (sorted by firstName ascending)
  - [ ] "Show all employees" toggle expands to all clocked-in employees (qualified employees still appear first, separated by a divider)
  - [ ] Selected employee's qualifying position is recorded on the completion record
  - [ ] If employee has multiple qualifying positions, the system records the first matching position (by schedulePositions.sortOrder)
  - [ ] Disabled/inactive employee accounts are excluded from the completion dialog
  - [ ] If no employees are clocked in at all, dialog shows empty state with toggle to show all active employees regardless of clock status

#### Feature 6: Out-of-Position Completion Tracking
- **User Story:** As a store manager, I want to know when tasks are completed by someone other than the assigned person or by someone without the required position so I can identify training or scheduling gaps.
- **Acceptance Criteria:**
  - [ ] Two severity levels tracked:
    - **Level 1 — Wrong Person:** Task assigned to a specific employee, completed by someone else
    - **Level 2 — Wrong Position:** Task requires a position, completed by someone without that position
  - [ ] Out-of-position completions require a free-text reason from the completer
  - [ ] Reason and severity stored in the completion audit record
  - [ ] Completions by someone with the correct position (even if not the specifically assigned person) are NOT flagged as out-of-position

#### Feature 7: Workbook Task List Display
- **User Story:** As any user viewing the workbook, I want to see who or what position each task is assigned to at a glance.
- **Acceptance Criteria:**
  - [ ] Person-assigned tasks show employee avatar/initials
  - [ ] Position-assigned tasks show a colored position badge (using position color)
  - [ ] Group-inherited assignments shown with a slightly different visual treatment (e.g., lighter opacity) vs. direct assignments
  - [ ] Multiple positions show primary badge + "+N" count
  - [ ] Unassigned tasks show no badge (clean, as today)
  - [ ] Carryover tasks with stale person assignments show a faded/dashed visual indicator

#### Feature 8: Shift Dialog Task Assignment
- **User Story:** As a store manager using BuyerKiosk native scheduling, I want to assign tasks to an employee directly from their shift dialog so I can plan tasks while I plan the schedule.
- **Acceptance Criteria:**
  - [ ] Shift create/edit dialog includes a collapsible "Tasks" section (collapsed by default to avoid overloading the dialog)
  - [ ] Shows unassigned tasks for the shift's date
  - [ ] Position-matching tasks (matching employee's positions) appear first, with a colored left border using the matching position color
  - [ ] Remaining unassigned tasks appear below a "Other Tasks" divider
  - [ ] Selecting a task creates a person assignment for that date, linked to the shift
  - [ ] Can assign entire task groups (group header checkbox) or individual tasks
  - [ ] Task completion records linked to the shift ID when assigned via shift dialog
  - [ ] Requires `workbook_manage_tasks` permission to see/use the Tasks section

#### Feature 9: Daily Task Assignment View
- **User Story:** As a store manager with BuyerKiosk native scheduling, I want a single view to see and manage all task assignments for today so I can quickly ensure every task group has the right people or positions.
- **Acceptance Criteria:**
  - [ ] Accessible from both the workbook (panel/tab) and the schedule page (panel)
  - [ ] Shows all task groups for the selected date with current assignment status
  - [ ] Groups show: default position assignment, any per-day override, individual task overrides
  - [ ] Manager can reassign groups or individual tasks from this view
  - [ ] Changes take effect immediately (auto-save with debounce; optimistic UI update, revert on failure with toast error) and reflect in the workbook via Ably event
  - [ ] Web-based view ships as Must Have; Mobile API for BuyerKiosk Live app is a Should Have (see Feature 10)

### Should Have Features

#### Feature 10: Mobile API for Daily Task Assignment (Live App)
- **User Story:** As a store owner/manager using the BuyerKiosk Live app, I want to view and manage daily task assignments from my phone so I can delegate tasks remotely.
- **Acceptance Criteria:**
  - [ ] GET endpoint returns all task groups with assignments for a date
  - [ ] PUT endpoint allows reassigning groups or tasks to positions or people
  - [ ] Response includes position and employee details for display
  - [ ] Proper permission checks (manager+ role required)

#### Feature 11: Out-of-Position Completion Report
- **User Story:** As a store manager, I want to review a report of all out-of-position task completions so I can identify patterns and take corrective action.
- **Acceptance Criteria:**
  - [ ] Report shows completions flagged as Level 1 or Level 2
  - [ ] Filterable by date range, task group, employee, severity level
  - [ ] Shows: task name, assigned to (person/position), completed by, reason, severity, date
  - [ ] Available as a section within existing task completion reports

### Could Have Features

#### Feature 12: Auto-Suggest Assignments Based on Schedule
- **User Story:** As a store manager, I want the system to suggest task assignments based on who's scheduled and their positions, so I spend even less time on delegation.
- **Acceptance Criteria:**
  - [ ] When opening daily assignment view, system suggests person assignments based on scheduled shifts and position matches
  - [ ] Suggestions shown as "recommended" with one-click accept
  - [ ] Manager can accept all suggestions or modify individually

#### Feature 13: Task Assignment Notifications
- **User Story:** As a team member, I want to be notified when a task is specifically assigned to me so I don't miss it.
- **Acceptance Criteria:**
  - [ ] Ably real-time notification when a task is person-assigned to an employee
  - [ ] Notification appears in workbook and optionally via Staff Chat

### Won't Have (This Phase)

- **Task dependencies/sequencing:** Tasks must be completed in a specific order (e.g., "Count inventory before processing backstock"). Future phase.
- **Position-based auto-scheduling of tasks:** Automatically creating task instances when someone with a specific position clocks in. Keep it simple — position is just an eligibility filter.
- **Cross-store task templates:** Sharing task groups and position mappings across multiple stores. Each store configures independently.
- **Time tracking per task:** Tracking how long each task takes to complete. Out of scope.
- **Approval workflows:** Requiring manager approval before marking a task complete. Not needed.
- **Recurring person assignments:** "Casey always does Closing on Wednesdays." Daily overrides only — no recurring person patterns.

## Detailed Feature Specifications

### Feature: Position-Aware Completion Dialog

**Description:** When a user completes a task that has a position requirement, the completion dialog intelligently filters the employee list to show the most relevant people first, while still allowing override with audit tracking.

**User Flow:**

1. User taps "Complete" on a task assigned to the "Inventory" position
2. System checks which employees are currently clocked in AND have the "Inventory" position
3. Dialog shows list of qualifying clocked-in employees (avatars + names)
4. User selects an employee → Task marked complete, qualifying position recorded
5. **If no qualifying employees are clocked in:** Dialog shows empty state with message "No employees with the Inventory position are currently clocked in" and the "Show all employees" toggle
6. **If user toggles "Show all employees":** Full list of clocked-in employees appears (non-qualifying employees shown without position badge)
7. **If user selects a non-qualifying employee:** Warning appears: "This task requires the Inventory position. [Employee] does not have this position. Please provide a reason." → Free-text input → Confirm → Task completes with Level 2 out-of-position flag

**Business Rules:**

- Rule 1: Position matching uses the `employeeSchedulePositions` junction — an employee qualifies if they hold ANY of the task's required positions
- Rule 2: If a task is assigned to BOTH a position and a specific person (person override for the day), the person assignment takes priority. Completion dialog pre-selects that person.
- Rule 3: When completing a person-assigned task, if someone other than the assigned person completes it, it's Level 1 (wrong person). If that person also lacks the position, it's Level 2 (wrong position) — use the higher severity.
- Rule 4: A task inherited from a group assignment follows the same rules as a directly assigned task
- Rule 5: The "qualifying position" recorded on completion is the specific position that matched, not all of the employee's positions
- Rule 6: Self-completion by the assigned person with the correct position = clean completion, no flags

**Edge Cases:**

- **No one clocked in at all:** Dialog shows "No employees are currently clocked in. Show all employees?" toggle that expands to all active employees (regardless of clock status)
- **Employee has multiple qualifying positions:** System records the first matching position (by sort order). No user prompt needed.
- **Task has no position requirement and no person assignment:** Standard completion flow — show all clocked-in employees, no out-of-position tracking
- **Person-assigned task where the person is not clocked in:** Dialog shows the assigned person at the top (greyed out/indicated as not clocked in), then clocked-in employees. If someone else completes it, Level 1 flag.
- **Task group override for the day + individual task override:** Individual task override wins. Group override applies to all other tasks in the group.
- **Position deactivated after assignment:** Task retains the position assignment but shows "position inactive" badge. Completion dialog falls back to "Show all employees" mode. Manager prompted to update assignment in admin.
- **Position renamed after assignment:** Display name updates automatically since the task stores positionId, not the name string. No action needed.
- **Carryover task with per-day person override from previous day:** Person override expires — carryover task reverts to default position assignment with "stale" indicator showing previous assignee name for context.
- **Disabled/terminated employee was person-assigned:** Task shows the person's name greyed out with "(Inactive)" label. Manager prompted to reassign.
- **Timezone edge case:** All date-specific assignments use the store's configured timezone for day boundary calculation. A shift starting at 11pm in EST is assigned to that EST date.
- **Concurrent reassignment:** Last write wins. If two managers reassign the same task simultaneously, the later save overwrites. No locking — acceptable given low conflict likelihood.

### Feature: Shift Dialog Task Assignment

**Description:** When creating or editing a shift for an employee, the shift dialog includes a task assignment section allowing managers to assign tasks for that shift's date.

**User Flow:**

1. Manager opens shift dialog (create or edit) for employee "Casey" on Feb 20
2. "Tasks" section at bottom of dialog shows available tasks for Feb 20
3. Tasks are organized: position-matching tasks first (highlighted, matching Casey's positions), then all other unassigned tasks
4. Manager checks tasks/groups to assign. Entire groups can be selected with a single checkbox.
5. On save, selected tasks get a person assignment to Casey for Feb 20, linked to this shift
6. Workbook for Feb 20 now shows Casey's avatar on those tasks

**Business Rules:**

- Rule 1: Only shows tasks that are not already person-assigned for that date (position-assigned or unassigned tasks are fair game)
- Rule 2: Assigning via shift dialog creates a shift-linked person assignment (stores shiftId)
- Rule 3: If the shift is deleted, the task person assignments created from it remain (don't cascade delete)
- Rule 4: If the shift date changes, task assignments for the old date are removed and new ones created for the new date
- Rule 5: Task groups appear as collapsible sections. Checking the group header assigns all tasks in the group.

**Edge Cases:**

- **Shift spans midnight:** Tasks are assigned to the date the shift STARTS on
- **Employee already person-assigned to a task:** That task appears as already checked/assigned (read-only) with "(Already assigned)" label
- **Task has been completed already:** Completed tasks don't appear in the assignment list
- **No unassigned tasks for the date:** Section shows "No tasks available for assignment" message

### Feature: Daily Task Assignment View

**Description:** A unified view showing all task groups for a given date with their current assignments, enabling rapid reassignment.

**User Flow:**

1. Manager accesses view from workbook ("Assignment" tab) or schedule page ("Task Assignments" panel)
2. View shows a card for each task group, organized by their default schedule order
3. Each group card shows: group name, default position assignment, per-day override (if any), count of tasks, completion progress
4. Manager can: click a group card to reassign the whole group, expand to see individual tasks, click individual tasks to override
5. Reassignment options: select from positions dropdown, or search/select a specific employee
6. Changes save immediately (no "Save" button — auto-save with debounce)

**Business Rules:**

- Rule 1: View defaults to today's date. Date picker allows viewing/editing other future dates (not past).
- Rule 2: Completed tasks within a group are shown but not reassignable
- Rule 3: When reassigning a group, only non-individually-overridden tasks are affected
- Rule 4: Permission required: `workbook_manage_tasks` or `uri_store_settings`

## Success Metrics

### Key Performance Indicators

- **Adoption:** 60% of stores with BuyerKiosk native scheduling configure at least one position-based task or group assignment within 30 days of feature launch. "Configure" = at least one `task.position_assigned` or `task.group_assigned` event recorded.
- **Engagement:** Average 5+ daily task assignment actions per active manager (via shift dialog or daily view). "Active manager" = user with `workbook_manage_tasks` permission who has logged in within the last 7 days. Actions counted: `task.person_assigned`, `task.group_assigned`, `daily_assignment.reassigned`.
- **Quality:** <5% of task completions flagged as out-of-position (Level 1 or Level 2) per store per month. Measured as: `count(completions where outOfPositionLevel > 0) / count(all completions with position or person assignment)`.
- **Business Impact:** Reduction in daily assignment session duration. Measured as time between first `daily_assignment.viewed` event and last `daily_assignment.reassigned` event in the same session. Baseline to be established in first 2 weeks, target 40% reduction by week 8.

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `task.position_assigned` | taskId, positionIds[], groupId, isGroupLevel | Track adoption of position-based assignment |
| `task.person_assigned` | taskId, userId, date, source (shift_dialog/daily_view/admin), shiftId? | Track person assignment patterns and entry points |
| `task.group_assigned` | groupId, positionIds[] or userId, date, isOverride | Track group-level assignment usage |
| `task.completed` | taskId, completedByUserId, qualifyingPositionId?, outOfPositionLevel (0/1/2), reason? | Core completion tracking with position audit |
| `task.completion_override` | taskId, assignedTo, completedBy, reason, level | Specific out-of-position event for reporting |
| `daily_assignment.viewed` | date, source (workbook/schedule/mobile) | Track which entry points managers prefer |
| `daily_assignment.reassigned` | taskId/groupId, fromAssignment, toAssignment, source | Track daily reassignment activity |
| `shift_dialog.tasks_assigned` | shiftId, userId, taskIds[], date | Track shift-dialog task assignment adoption |

---

## Audit & Privacy

### Out-of-Position Reason Visibility
- **Who can view:** Users with `workbook_manage_tasks` or `uri_store_settings` permission (managers and above)
- **What's visible:** Completion record details including the reason text, severity level, who completed it, and when
- **Team members** can see that a task was completed and by whom, but NOT the out-of-position reason text or severity flag
- **Report access:** Out-of-position completion report requires `uri_store_settings` permission (store admin level)

### Data Retention
- Out-of-position reasons are stored indefinitely as part of the completion audit record (same retention as existing `workbook_task_completions`)
- No automatic purging — follows the same data lifecycle as other store operational data
- Reasons are plain text, no PII beyond the employee name already stored on the completion

### Privacy Considerations
- Out-of-position tracking is an operational quality metric, not a disciplinary tool
- Reason field is free-text — staff should be instructed to note operational reasons (e.g., "covering for absent colleague") not personal details
- No automated alerts or escalations based on out-of-position frequency (reports are pull-based, not push)

## Constraints and Assumptions

### Constraints
- **BuyerKiosk native scheduling required:** Position features only available for stores using BuyerKiosk native scheduling (not WhenIWork/Homebase)
- **Existing task infrastructure:** Must build on existing `workbook_task_*` tables and `TasksApiController` — no greenfield rebuild
- **Performance:** Task list rendering must remain under 200ms even with assignment data. Schedule panel cached in Redis.
- **Mobile API:** Must follow existing `/api/mobile/` patterns for Live app compatibility

### Dependencies
- **Schedule Positions system:** `schedulePositions` table in store DB (already exists, created by migration `20251220_013_004`)
- **Employee Position Assignments:** `employeeSchedulePositions` junction table (already exists, created by migration `20260219_001`)
- **Clock-in system:** Real-time clock status via `timePunches` table + Ably events for live updates
- **Shift data:** `shifts` table with `positionId` FK for position-aware shift matching
- **Permission gates:** `workbook_manage_tasks`, `uri_store_settings`, `uri_schedule`, `uri_schedule_config`
- **Ably:** Real-time event publishing for task assignment/completion updates
- **Redis:** Caching for schedule panel and task list data
- **Store eligibility:** Feature gated by `store.schedulingProvider === 'buyerkiosk'` check

### Assumptions
- Stores using BuyerKiosk native scheduling already have positions configured via the existing `schedulePositions` system
- Employees already have positions assigned via `employeeSchedulePositions` (seeded by migration)
- The clock-in system accurately reflects who is currently working (real-time via Ably)
- Managers will configure position defaults once and only use per-day overrides occasionally
- Store timezone setting is accurate (used for date-specific assignments)

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Managers don't configure positions, rendering feature useless | High | Medium | Auto-suggest assignments based on schedule. Show onboarding prompt when task admin is opened with no positions assigned. |
| Too many out-of-position completions frustrate the team | Medium | Low | Keep the override flow fast (one reason field, no approval). Report is opt-in, not in-your-face. |
| Shift dialog becomes overloaded with task assignment UI | Medium | Medium | Tasks section is collapsible and starts collapsed. Only expands on click. Minimal footprint. |
| Daily assignment view creates duplicate workflows | Low | Medium | Clear guidance: admin page for defaults, daily view for overrides. Different purpose, different frequency. |
| Mobile API scope creep delays delivery | High | Medium | Mobile API is "Should Have" — can ship web-first and add mobile API in fast follow. |

## Open Questions

- [x] Should position assignment be multi-select? → **Yes, multiple positions per task**
- [x] Should group assignment cascade or be independent? → **Cascade as default, task overrides**
- [x] Should completion track the qualifying position? → **Yes, specific position recorded**
- [x] Should non-native-scheduling stores get employee-only assignment? → **No, feature requires native scheduling**
- [x] How should carryover tasks handle stale assignments? → **Keep but flag as stale**
- [x] Should shift dialog task assignment link to the shift? → **Yes, shiftId stored on completion**

All open questions resolved during requirements gathering.

---

## Supporting Research

### Competitive Analysis

- **Homebase Tasks:** Supports assigning tasks to employees but not to roles/positions. No position-aware completion tracking.
- **7shifts Task Management:** Allows task assignment to individuals with completion tracking. No role-based assignment.
- **Deputy Task Management:** Supports area/location-based tasks but not position-based. Basic completion audit.
- **Our differentiator:** Position-based assignment with cascading group defaults and out-of-position audit trail is unique in the SMB retail space.

### User Research

- Store managers report spending 10-15 minutes daily assigning recurring tasks to whoever is working that day
- "Closing procedures" and "Opening procedures" are the most commonly mentioned task groups that should "just go to whoever is closing/opening"
- Managers want to know if tasks are being done by qualified people but don't want to create friction for the team

### Market Data

- 78% of BuyerKiosk stores with native scheduling have configured at least 3 custom positions
- Average store has 2.5 task groups with 8 tasks per group
- 40% of task completions happen during the last 2 hours of the closing shift