focus-flow/Codex Documentation/Current Software Plan/V1_BLOCK_05_Recurring_Locked_Blocks.md

V1 Block 05 — Recurring Locked Blocks

Status: Planned

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

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.

Chunk 5.4 — Track completed during locked hours

Recommended Codex level: medium

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.

Commit suggestion:

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