focus-flow/Codex Documentation/Archived plans/V1_BLOCK_02_Domain_Model.md

V1 Block 02 — Domain Model

Status: Completed

Purpose: Define the core data vocabulary for the scheduling app. This model should be UI-independent and testable.

Chunk 2.1 — Define core enums

Recommended Codex level: medium

Status: Completed with environment blocker noted

Tasks:

Add or verify enums for:

• TaskType: flexible, inflexible, critical, locked, surprise, freeSlot.
• TaskStatus: planned, active, completed, missed, cancelled, noLongerRelevant, backlog.
• PriorityLevel: veryLow, low, medium, high, veryHigh.
• RewardLevel: veryLow, low, medium, high, veryHigh, notSet.
• DifficultyLevel: veryEasy, easy, medium, hard, veryHard, notSet.
• ReminderProfile: silent, gentle, persistent, strict.

Rules:

• Reward notSet is its own category and must not be treated as low.
• Difficulty may have notSet for raw capture/default states.
• Critical and inflexible are required visible items.
• Locked blocks are hidden scheduling constraints, not ordinary tasks.

Acceptance criteria:

• Enums exist in the domain model.
• Comments document the business meaning of each value.
• Tests can import and use the enum values.

Execution notes:

• Verified all required enum values exist in lib/src/models.dart.
• Added business-meaning documentation comments for status, priority, reward, difficulty, and reminder values.
• Preserved RewardLevel.notSet and DifficultyLevel.notSet as neutral capture/default states.
• Added a test that imports and references core enum values through the public package export.

Chunk 2.2 — Define task identity and fields

Recommended Codex level: high

Status: Completed with environment blocker noted

Tasks:

Create or refine a Task model with fields for:

• id
• title
• projectId
• type
• status
• priority
• reward
• difficulty
• durationMinutes
• scheduledStart
• scheduledEnd
• parentTaskId
• createdAt
• updatedAt
• stats

Rules:

• Use a copy/update pattern rather than mutating shared state unexpectedly.
• Allow optional fields for quick capture.
• Do not require every task to have reward/difficulty/time.
• Include validation helper(s) only if needed.

Acceptance criteria:

• A task can represent backlog, planned, critical, locked, and surprise items.
• A quick-capture task can be created with minimal fields.
• Tests cover default/neutral quick-capture values.

Execution notes:

• Kept the immutable Task model and copyWith update pattern.
• Added Task.quickCapture for minimal capture with neutral defaults and no required schedule details.
• Added tests for quick-capture defaults, including RewardLevel.notSet, DifficultyLevel.notSet, and absent schedule/duration.

BREAKPOINT: Stop here. The next chunk remains high but may expand model scope.

Chunk 2.3 — Define project and project defaults

Recommended Codex level: high

Status: Completed with environment blocker noted

Tasks:

Create a minimal ProjectProfile or equivalent model with:

• id
• name
• colorKey or theme token
• default priority
• default reward
• default difficulty
• default reminder profile
• default duration minutes

Rules:

• Project defaults are suggestions/defaults, not hard requirements.
• Individual tasks can override project defaults.
• Learned usage statistics are future-facing; do not overbuild now.

Acceptance criteria:

• Tasks can reference a project.
• Project defaults can be applied when creating a task.
• Overrides remain possible.

Execution notes:

• Kept ProjectProfile minimal with id, name, color key, default priority, default reward, default difficulty, default reminder profile, and default duration.
• Added ProjectProfile.createTask to apply project defaults while allowing explicit task overrides.
• Added tests for default application and per-task overrides.

Chunk 2.4 — Define task statistics model

Recommended Codex level: medium

Status: Completed with environment blocker noted

Tasks:

Add or verify a TaskStatistics model with counters for:

• skippedDuringBurnoutCount
• manuallyPushedCount
• autoPushedCount
• movedToBacklogCount
• restoredFromBacklogCount
• missedCount
• cancelledCount
• completedLateCount
• completedDuringLockedHoursCount
• completedDuringLockedHoursMinutes

Rules:

• Stats are internal metadata.
• Stats should support future filtering/reporting.
• Do not build report UI in V1.

Acceptance criteria:

• Statistics can be incremented through copy/update helpers.
• Tests cover at least one increment path.

Execution notes:

• Verified all required statistics counters exist.
• Added immutable increment helpers for remaining counters.
• Added a test covering a statistics increment path and preservation of existing values.
• 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.

Commit suggestion:

feat(domain): define scheduling task model