# Grounded

*A to-do app that doesn't believe you.*

Most to-do apps are neutral ledgers — they record intent and never object when
you ignore it. Grounded is an **enforcement layer**: it holds a model of what
you committed to, notices when reality diverges, and imposes escalating
consequences you agreed to in advance.

Design axiom: **the checkbox is the enemy.** Every feature exists because
self-reported completion is worthless to someone trying to stop lying to
themselves.

---

## Repository

```
frontend/     Flutter app (Android · iOS · Web · Windows)
```

See [`frontend/CLAUDE.md`](frontend/CLAUDE.md) for the architecture and
conventions, and [`frontend/design.md`](frontend/design.md) for the design
language.

---

## The model

Three primitives; everything else is derived.

| Primitive | Meaning |
|---|---|
| **Commitment** | Something you said you'd do. Has a due *window*, a class, and a proof requirement. |
| **Debt** | The weight of what you've missed — a decaying, weighted score rather than a count. |
| **Standing** | `Good → Warned → Grounded → Lockdown`. Derived from debt; decides what the app lets you do. |

Streaks reward perfection and collapse permanently on one miss. Debt is
continuous, forgiving in shape, hard to ignore, and gives you a way back.

**Goals** contain commitments — "Workout" holds "Monday shoulders". A goal
never carries debt; the tasks inside it do.

---

## What makes it different

- **Due windows, not due dates.** `Mon 06:00–08:00` can actually close. A miss
  is a permanent event, never a silent rollover to today.
- **Capacity blocking.** Chronic overdue is usually overcommitment misdiagnosed
  as laziness. The app plans against what you *historically complete*, learns
  your per-category estimation multiplier, and refuses plans that don't fit.
- **Excuses get clustered.** *"'Too tired' has appeared 14 times this month, 11
  of them on gym days, 9 of them after 7pm. Consider moving gym to morning."*
- **Proof of completion.** Honour · Photo · Timer · Location · Health · Witness.
  Completing outside the window records as *late complete* — distinct in
  history, and it never reduces debt to zero.
- **A live runner.** Starting a task takes over the screen, keeps time from
  wall-clock so screen-off can't cheat it, and pauses when you leave the app.
- **Plyometrics is where it stops you.** Weekly ground-contact ceilings and
  enforced recovery gaps — connective tissue doesn't recover on a motivation
  schedule.

## And what keeps it usable

An app built on guilt has an obvious failure mode: the people who need it most
delete it during their worst week. So — rationed **amnesty tokens**, **sick and
travel mode** that pauses debt entirely, a **tone slider** hard-capped so no
copy ever attacks the person rather than the behaviour, and **distress
detection** that drops the strict persona completely when debt spikes while
engagement and readiness fall. Strictness is never the response to someone who
is actually struggling.

---

## Running it

```bash
cd frontend
cp .env.example .env      # then point it at your backend
flutter pub get
flutter run
```

Requires Flutter with Dart `^3.6.2`.

---

## Status

Frontend scaffold complete: the full architecture, the debt/standing/capacity/
integrity engines, and every screen in the MVP cut. The backend is not in this
repository yet — `CommsDirections.dart` defines the contract it needs to
satisfy.