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

V1 Block 03 — Scheduling Engine

Status: Planned

Purpose: Implement the core behavior that makes this product valuable: flexible tasks move safely without destroying the user's intended order.

Chunk 3.1 — Define scheduling inputs and outputs

Recommended Codex level: high

Status: Completed with environment blocker noted

Tasks:

Create clear models/functions for scheduling operations:

• Current task list.
• Locked intervals.
• Required visible intervals.
• Flexible intervals/tasks.
• Scheduling window.
• Operation result with changed tasks and notices.

Rules:

• Scheduling functions should be deterministic.
• Avoid direct database access inside the engine.
• Return results; do not hide side effects.

Acceptance criteria:

• Scheduling engine can be called with in-memory data.
• Result object can describe moved tasks and overlaps.
• Tests can assert exact task placement results.

Execution notes:

• Added SchedulingWindow, SchedulingInput, SchedulingChange, and SchedulingOverlap models.
• Expanded SchedulingResult and SchedulingNotice so operation results can report changed task placements, overlap details, and typed notices.
• Added SchedulingEngine.analyzeSchedule for deterministic in-memory schedule analysis without moving tasks or touching persistence.
• Added tests for in-memory task grouping, overlap reporting, and exact movement-change representation.
• Could not run dart analyze or dart test because neither dart nor flutter is installed on PATH in this environment.
• Commit was deferred until the repository was initialized and repaired.

Chunk 3.2 — Insert backlog task into next available flexible slot

Recommended Codex level: extra high

Status: Completed with environment blocker noted

Tasks:

Implement insertion behavior:

• A backlog item can be inserted into the soonest flexible slot where it fits.
• Later flexible tasks shift forward using normal bump rules.
• Locked, inflexible, and critical blocks do not move.
• If no slot exists today, return a clear overflow result.

Acceptance criteria:

• Test: insert 15-minute task into an open 20-minute slot.
• Test: insert task before flexible task and push later flexible task.
• Test: insertion skips locked time.
• Test: insertion does not move inflexible/critical blocks.
• Test: no available slot returns an overflow/no-fit result.

Execution notes:

• Added SchedulingEngine.insertBacklogTaskIntoNextAvailableSlot.
• Backlog insertion now requires a flexible backlog task with positive duration.
• The insertion planner schedules the task into the earliest available in-window slot, skips locked/required visible time, and preserves planned flexible task order while pushing affected flexible tasks later.
• Locked, inflexible, critical, and non-planned scheduled flexible intervals are treated as fixed for this operation.
• Successful insertion returns updated tasks, movement notices, and exact SchedulingChange records.
• No-fit and overflow cases return the original task list with a typed notice.
• Added tests for open-slot insertion, bumping a later flexible task, skipping locked time, preserving inflexible/critical blocks, and overflow/no-fit.
• Could not run dart analyze or dart test because neither dart nor flutter is installed on PATH in this environment.
• Commit was deferred until the repository was initialized and repaired.

BREAKPOINT: Stop here. Confirm extra high mode before starting this chunk if not already set.

Chunk 3.3 — Push flexible task to next available slot

Recommended Codex level: extra high

Tasks:

Implement push behavior:

• Push -> Next available slot moves the selected flexible task to the next slot where it fits.
• Later flexible tasks shift forward.
• Preserve order among affected flexible tasks.
• Do not move locked, inflexible, or critical blocks.

Acceptance criteria:

• Test: pushed flexible task moves after current slot.
• Test: downstream flexible tasks are bumped in order.
• Test: locked intervals are respected.
• Test: required items remain fixed and visible.

Chunk 3.4 — Push flexible task to tomorrow top of queue

Recommended Codex level: high

Tasks:

Implement tomorrow behavior:

• Push -> Tomorrow places the task at the top of tomorrow's flexible queue.
• Preserve order among multiple rolled/pushed tasks where applicable.
• Do not require manual scheduling.

Acceptance criteria:

• Test: task receives tomorrow date/queue marker.
• Test: task is before other flexible tomorrow tasks unless required/locked time blocks it.

BREAKPOINT: Stop here. The next chunk drops from high/extra high to medium.

Chunk 3.5 — End-of-day rollover

Recommended Codex level: medium

Tasks:

Implement rollover behavior:

• At end of day, unfinished flexible tasks move to tomorrow.
• Rolled tasks go to top of tomorrow's flexible queue.
• Preserve order among rolled-over tasks.
• Produce a small notice such as 3 unfinished flexible tasks were moved to tomorrow.

Do not roll over:

• Locked blocks.
• Inflexible tasks.
• Critical tasks without explicit missed/backlog handling.
• Cancelled tasks.
• Completed tasks.

Acceptance criteria:

• Tests cover all included and excluded task types.
• Notice text/count is generated.

Commit suggestion:

feat(scheduling): implement flexible task movement rules