# V1 Block 05 — Recurring Locked Blocks

Status: Completed

Purpose: Locked blocks are critical MVP. They reserve time, stay hidden by default, and are not tasks.

## Chunk 5.1 — Locked block model

Recommended Codex level: high

Status: Completed

Tasks:

Create a model for locked blocks with:

- id
- name
- start/end time
- recurrence rule or simple recurrence model
- hiddenByDefault flag
- project/category optional field
- created/updated timestamps

Rules:

- Locked blocks are scheduling constraints.
- They must not render as ordinary tasks.
- They may have names in overlay mode.

Acceptance criteria:

- Model supports one-off and recurring locked blocks.
- Work-hours style recurrence can be represented.

Execution notes:

- Added `ClockTime`, `LockedWeekday`, `LockedBlockRecurrence`, and `LockedBlock`.
- Locked blocks include id, name, start/end time, optional recurrence, hidden-by-default flag, optional project id, and created/updated timestamps.
- Locked blocks remain scheduling constraints and are not modeled as ordinary tasks.
- One-off locked blocks and weekday work-hours recurrence are represented.
- Added tests for one-off locked blocks and weekday work-hours recurrence.
- `dart analyze` and `dart test` passed.

## Chunk 5.2 — One-day override model

Recommended Codex level: high

Status: Completed

Tasks:

Support one-day overrides for recurring locked blocks:

- remove a locked occurrence for a date
- shorten/extend an occurrence for a date
- add surprise locked time for a date
- avoid changing the base recurrence rule

Acceptance criteria:

- Test: Friday off removes only Friday occurrence.
- Test: half-day modifies only one date.
- Test: recurring rule remains unchanged.

Execution notes:

- Added `LockedBlockOverrideType` and `LockedBlockOverride`.
- Overrides support removing one occurrence, replacing one occurrence's times, and adding surprise locked time for one date.
- Override objects do not mutate the base recurrence rule.
- Added tests for Friday-off removal, half-day replacement, surprise locked time, and unchanged recurrence.
- `dart analyze` and `dart test` passed.

BREAKPOINT: Stop here. Confirm `high` mode before handling recurrence/override expansion.

## Chunk 5.3 — Expand locked blocks into schedule constraints

Recommended Codex level: extra high

Status: Completed

Tasks:

Implement expansion from recurring locked blocks + overrides into concrete intervals for a day.

Rules:

- Hidden-by-default affects UI only, not scheduling.
- The scheduling engine must always respect locked intervals.
- Overlay mode can reveal names and times.

Acceptance criteria:

- Test: recurring work block appears on weekdays.
- Test: one-day override removes/modifies the occurrence.
- Test: scheduling engine sees the final locked intervals.

Execution notes:

- Added an explicit `date` field for one-off locked blocks so non-recurring constraints have a testable calendar anchor.
- Added `LockedBlockOccurrence`, `LockedScheduleExpansion`, `expandLockedBlocksForDay`, and `lockedSchedulingIntervalsForDay`.
- Expansion resolves weekly recurrence, one-day remove/replace overrides, and added surprise locked time for a target day.
- Hidden-by-default remains occurrence metadata only; scheduler-facing intervals are always returned for scheduling.
- Added tests for weekday recurrence expansion, one-day remove/replace behavior, surprise locked time expansion, and scheduling engine use of final expanded locked intervals.
- `dart format lib test`, `dart analyze`, `dart test`, and `git diff --check` passed.

## Chunk 5.4 — Track completed during locked hours

Recommended Codex level: medium

Status: Completed

Tasks:

Add helper logic to detect when a completed/surprise task overlaps locked time.

Track:

- completedDuringLockedHoursCount
- completedDuringLockedHoursMinutes
- projects completed during locked hours, if project stats exist

Acceptance criteria:

- Tests cover task completed entirely inside locked time.
- Tests cover partial overlap.
- Tests cover no overlap.

Execution notes:

- Added `completedDuringLockedHoursMinutes` to calculate completed/surprise task overlap with locked intervals.
- Added `trackCompletedDuringLockedHours` to return an updated task with locked-hour completion statistics when overlap exists.
- Overlap calculation merges intersecting locked intervals before counting minutes to avoid double counting.
- Added tests for tasks entirely inside locked time, partial overlap, no overlap, surprise task overlap, and overlapping locked intervals.
- `dart format lib test`, `dart analyze`, `dart test`, and `git diff --check` passed.

Commit suggestion:

```text
feat(locked-time): support recurring hidden scheduling blocks
```