ADHD Scheduling App Core

This is a pure Dart scheduling-core project for an ADHD-focused scheduling application.

The repository intentionally keeps the scheduling core pure Dart before adding a full Flutter UI. The hardest part of the product is the scheduling behavior: flexible task shifting, locked time, backlog recovery, recurring availability blocks, and task-state correctness. Keeping that logic independent makes it easier to test and safer to hand off to Codex.

Current V1 core status

• Implemented V1 core: Today timeline view models, backlog/wishlist behavior, quick capture, flexible task insertion/pushing, recurring hidden locked blocks, one-day locked-block overrides, required task state transitions, surprise task logging, child task ownership/completion, internal statistics, and persistence-preparation helpers.
• V2.0: Week/month views, reports, overwhelm shield, drag-and-drop, task history panels.
• Persistence direction: MongoDB is the committed database target. Current V1 work prepares repository interfaces and document-shaped mappings only; it does not add a MongoDB adapter, connection string, Atlas setup, local server requirement, accounts, sync, or background service.
• Wishlist/future: Dependencies, context tags, advanced sync, actual MongoDB adapter/runtime setup, long-running task behavior decisions.

Repository layout

.
├── AGENTS.md
├── README.md
├── pubspec.yaml
├── analysis_options.yaml
├── lib/
│   ├── scheduler_core.dart
│   └── src/
│       ├── backlog.dart
│       ├── child_tasks.dart
│       ├── document_mapping.dart
│       ├── locked_time.dart
│       ├── models.dart
│       ├── persistence_contract.dart
│       ├── quick_capture.dart
│       ├── repositories.dart
│       ├── scheduling_engine.dart
│       ├── task_actions.dart
│       ├── task_statistics.dart
│       └── timeline_state.dart
├── test/
│   ├── child_tasks_test.dart
│   ├── document_mapping_test.dart
│   ├── edge_case_regression_test.dart
│   ├── persistence_edge_cases_test.dart
│   ├── repositories_test.dart
│   ├── required_task_actions_test.dart
│   ├── scheduling_engine_test.dart
│   ├── surprise_task_logging_test.dart
│   └── timeline_state_test.dart
├── Human Documentation/
│   ├── Original Chat-Compiled Design Spec.md
│   ├── Overall App Design Spec.docx
│   ├── Starter Architecture Notes.md
│   └── Unified Product Design Summary.md
└── Codex Documentation/
    ├── README.md
    ├── Current Software Plan/
    └── Archived plans/

Basic commands

Install a Dart SDK that satisfies pubspec.yaml first. This is a pure Dart package, so Flutter is not required for the current core/test loop. MongoDB is the planned persistence target, but no MongoDB service, Atlas account, connection string, network access, or sync/background process is required for the current in-memory domain/test loop.

dart pub get
dart format lib test
dart analyze
dart test
git diff --check

Run these before committing changes whenever the local environment has Dart available.

Documentation

Product and design context belongs in Human Documentation/. Codex execution plans belong in Codex Documentation/, with active work under Codex Documentation/Current Software Plan/ and finished plans moved to Codex Documentation/Archived plans/.

Codex handoff

Codex should begin by reading:

1. AGENTS.md
2. Human Documentation/Overall App Design Spec.docx or the Markdown companion
3. Codex Documentation/Current Software Plan/README.md
4. The next numbered block document in Codex Documentation/Current Software Plan/

Each completed work block should be committed with a conventional commit message.