headroom/openspec/changes/archive/2026-03-08-capacity-expert-mode/specs/capacity-expert-mode/spec.md

ADDED Requirements

Requirement: Toggle Expert Mode

The system SHALL provide a toggle switch on the Capacity Planning page that enables or disables Expert Mode. The toggle SHALL be persisted in localStorage under the key headroom.capacity.expertMode so the user's preference survives page reloads.

Scenario: Toggle defaults to off

• WHEN a user visits the Capacity Planning page for the first time
• THEN Expert Mode is off and the standard calendar view is shown

Scenario: Toggle persists across reloads

• WHEN a user enables Expert Mode and reloads the page
• THEN Expert Mode is still enabled and the grid view is shown

Scenario: Toggle is right-aligned on the tabs row

• WHEN the Capacity Planning page is rendered
• THEN the Expert Mode toggle appears right-aligned on the same row as the Calendar, Summary, Holidays, and PTO tabs

Scenario: Switching mode with unsaved changes warns user

• WHEN a user has dirty (unsaved) cells in the Expert Mode grid
• AND the user toggles Expert Mode off
• THEN the system shows a confirmation dialog: "You have unsaved changes. Discard and switch?"
• AND if confirmed, changes are discarded and the calendar view is shown

---

Requirement: Display Expert Mode planning grid

The system SHALL render a dense planning grid when Expert Mode is enabled. The grid SHALL show all active team members as rows and all days of the selected month as columns.

Scenario: Grid shows all active team members

• WHEN Expert Mode is enabled for a given month
• THEN each active team member appears as a row in the grid
• AND inactive team members are excluded

Scenario: Grid shows all days of the month as columns

• WHEN Expert Mode is enabled for February 2026
• THEN the grid has 28 columns (one per calendar day)
• AND each column header shows the day number

Scenario: Weekend columns are visually distinct

• WHEN the grid is rendered
• THEN weekend columns (Saturday, Sunday) are visually distinguished (e.g. muted background)

Scenario: Holiday columns are visually distinct

• WHEN a day in the month is a company holiday
• THEN that column header is visually marked as a holiday

Scenario: Grid loads existing availability data

• WHEN Expert Mode grid is opened for a month where availability overrides exist
• THEN each cell pre-populates with the stored token matching the saved availability value

---

Requirement: Cell token input and validation

The system SHALL accept exactly the following tokens in each grid cell: H, O, 0, .5, 0.5, 1. Any other value SHALL be treated as invalid.

Scenario: Valid token accepted on blur

• WHEN a user types 1 into a cell and moves focus away
• THEN the cell displays 1 and is marked valid

Scenario: Valid token .5 normalized on blur

• WHEN a user types .5 into a cell and moves focus away
• THEN the cell displays 0.5 and is marked valid with numeric value 0.5

Scenario: H and O accepted on any date

• WHEN a user types H or O into any cell (weekend, holiday, or working day)
• THEN the cell is marked valid with numeric value 0
• AND the display shows the typed token (H or O)

Scenario: Invalid token marked red on blur

• WHEN a user types 2 or abc or any value not in the allowed set into a cell and moves focus away
• THEN the cell border turns red
• AND the raw text is preserved so the user can correct it

Scenario: Submit disabled while invalid cell exists

• WHEN any cell in the grid has an invalid token
• THEN the Submit button is disabled

Scenario: 0 auto-renders as O on weekend column

• WHEN a user types 0 into a cell whose column is a weekend day and moves focus away
• THEN the cell displays O (not 0)
• AND the numeric value is 0

Scenario: 0 auto-renders as H on holiday column

• WHEN a user types 0 into a cell whose column is a company holiday and moves focus away
• THEN the cell displays H (not 0)
• AND the numeric value is 0

---

Requirement: Live KPI bar in Expert Mode

The system SHALL display a live KPI bar above the grid showing team-level Capacity (person-days) and Projected Revenue, updating in real time as cell values change.

Scenario: KPI bar shows correct capacity on load

• WHEN Expert Mode grid loads for a month
• THEN the KPI bar shows total team capacity in person-days matching the sum of all members' numeric cell values

Scenario: KPI bar updates when a cell changes

• WHEN a user changes a valid cell from 1 to 0.5
• THEN the KPI bar immediately reflects the reduced capacity and revenue without a page reload

Scenario: Invalid cells excluded from KPI totals

• WHEN a cell contains an invalid token
• THEN that cell contributes 0 to the KPI totals (not null or an error)

Scenario: Projected Revenue uses hourly rate and hours per day

• WHEN the KPI bar calculates projected revenue
• THEN revenue = SUM(member capacity in person-days × hourly_rate × 8 hours/day) for all active members

---

Requirement: Batch save availability from Expert Mode

The system SHALL allow saving all pending cell changes in a single batch operation via a Submit button.

Scenario: Submit saves all dirty valid cells

• WHEN a user has changed multiple cells and clicks Submit
• THEN the system sends a single batch request with all dirty cell values
• AND on success, all dirty flags are cleared and a success toast is shown

Scenario: Submit is disabled when no dirty cells exist

• WHEN no cells have been changed since the last save (or since load)
• THEN the Submit button is disabled

Scenario: Submit is disabled when any invalid cell exists

• WHEN at least one cell contains an invalid token
• THEN the Submit button is disabled regardless of other valid dirty cells

Scenario: Submit failure shows error

• WHEN the batch save API call fails
• THEN the system shows an error alert
• AND dirty flags are preserved so the user can retry

Scenario: Batch endpoint validates each availability value

• WHEN the batch endpoint receives an availability value not in [0, 0.5, 1]
• THEN the system returns HTTP 422 with a validation error message

---

Requirement: Batch availability API endpoint

The system SHALL expose POST /api/capacity/availability/batch accepting an array of availability updates for a given month.

Scenario: Batch endpoint saves multiple updates

• WHEN a POST request is made to /api/capacity/availability/batch with a valid month and array of updates
• THEN the system upserts each {team_member_id, date, availability} entry
• AND returns HTTP 200 with { "data": { "saved": <count>, "month": "<YYYY-MM>" } }

Scenario: Batch endpoint invalidates cache once

• WHEN a batch save completes for a given month
• THEN the month-level capacity cache is flushed exactly once (not once per row)

Scenario: Batch endpoint rejects invalid team_member_id

• WHEN a batch request contains a team_member_id that does not exist
• THEN the system returns HTTP 422 with a validation error

Scenario: Batch endpoint rejects invalid availability value

• WHEN a batch request contains an availability value not in [0, 0.5, 1]
• THEN the system returns HTTP 422 with a validation error

Scenario: Empty batch is a no-op

• WHEN a POST request is made with an empty updates array
• THEN the system returns HTTP 200 with { "data": { "saved": 0, "month": "<YYYY-MM>" } }