# 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

```text
.
├── 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.

```bash
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.