docs/SCHEDULE.md

Schedule / time-tracking

Additive Habit Journal feature: iOS-like day plan, thick block feedback, learned duration priors, Cursor agent pull/push, and OpenRouter/rules reschedule.

P1 scope lock (hard)

Ship only: day timeline + thick feedback (<20s) + priors/duration learning + yesterday-trigger / last-hour capacity cut.

Do not implement as code:

• full PERMA
• ωEᵢ, δᵢ, or H=S+C+V
• hedonic δ as an explicit v1 term (learn later via would_repeat + falling fun)
• split feedback into Meaning vs Flow / “meaningful?” / “in the zone?”
• family/relationship tasks as a pillar to maximize
• schedule as a substitute for Daily or Log

EV stays owned (no rewrite)

EV = P(done)*U + γ*I + η*Fun − λt*d_hat − λm*cost − λf*FSE

Seligman = operators, not a new religion:

• trigger day → raise λ_f and η; only P0 overrides cuts
• escape (porn / court / rerun binge) ≠ fun/explore
• fun/explore should yield data or skill contact

Feedback fields (v1 — no extras)

did · actual_min · quality 1–5 · fun 1–5 · energy_after −2…+2 · would_repeat · skip_reason · money optional.

Later mapping from data only: quality+would_repeat ≈ meaning; fun+energy ≈ recovery. Do not ask PERMA questions in UI.

Premortems (fail the PR if present)

Planning-as-avoidance · no feedback · OR thrash · overfull FSE day · schedule theater · guilt / duty-maximizer copy.

P0 never silent-reschedule

Sleep, food, Spain/visa deadlines stay locked at their times.

Nav IA (chosen)

Home | Plan | (+) Log | Daily | Settings

• Center FAB stays Log (one tap from every main screen).
• History remains at #/history and is reachable from Home (“See all” / History chip).

Data

Under DATA_ROOT/schedule/:

Path	Purpose
plan-YYYY-MM-DD.json	Versioned day plan
feedback.jsonl	Block feedback rows
priors.json	Per-kind d_hat, p_done, fun, slip
meta.json	Last reschedule timestamp

Math (server-owned)

d_hat = (n/(n+m)) * mean_actual + (m/(n+m)) * prior_default
slip = actual_min - planned_min
p_done ≈ (N_done + α) / (N + α + β)
C_today cut if yesterday_trigger or last-hour urge/court/corn/rerun (P0 still allowed)
health = (strong_feedback / planned) * p0_done_rate * (1 if explore/fun done else 0)

Strong feedback = did in done|partial and actual_min, quality, fun present.
LLM must not invent p_helped, rank, or %.

Human API (session cookie)

• GET/PUT /api/plan/{date}
• POST/PATCH/DELETE /api/plan/{date}/blocks[/{id}]
• POST /api/plan/{date}/blocks/{id}/feedback
• POST /api/plan/{date}/seed — empty day → template starter (P0 locked; capacity cuts)
• GET /api/schedule/priors
• GET /api/schedule/templates
• POST /api/plan/{date}/reschedule { "reason", "force" }
• GET /api/plan/{date}/health

GET /api/plan/{date} overlays live capacity_hint, operators, risk_1h, triggers_yesterday.

Agent API

Set Space secret AGENT_TOKEN.

# Pull context
curl -s -H "Authorization: Bearer $AGENT_TOKEN" \
  "https://YOUR_SPACE/api/agent/context?day=2026-07-19"

# Push plan
curl -s -X PUT -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"source":"cursor","blocks":[{"date":"2026-07-19","start":"09:00","end":"09:45","title":"Earn one ship","kind":"earn_ship","intent":"duty","priority":"P1","planned_min":45,"status":"planned","locked":false,"notes":"","version_added":1,"source":"cursor"}]}' \
  "https://YOUR_SPACE/api/agent/plan/2026-07-19"

Agent contract (one line)

Implement thin schedule loop + thick feedback + trigger capacity cuts. Seligman validates recovery and anti-duty-only design; do not expand the equation or feedback fields.

Steps

1. GET /api/agent/context?day=
2. Build ≤ max_blocks, pad with d_hat, keep P0 locked, ≥1 explore/restore unless capacity very low
3. PUT /api/agent/plan/{date}
4. User completes blocks on phone (thick feedback)
5. Optional POST /api/plan/{date}/reschedule when missed/risk

Context includes operators and capacity_hint.

Env

AGENT_TOKEN=...
OPENROUTER_API_KEY=...   # optional; rules backup if missing
RESCHEDULE_MIN_GAP_MIN=90
SCHEDULE_DAY_START=06:00
SCHEDULE_DAY_END=23:00
TZ / SCHEDULE_TIMEZONE=Africa/Dar_es_Salaam

UI map

Route	Role
#/plan	Day timeline 06:00–23:00, now line, colored blocks
Block sheet	Complete with did / minutes / quality / fun (no PERMA Qs)
Home	Next 1–2 blocks + overdue feedback banner; empty → Paste plan CTA
Plan	Paste ChatPlan / Export for chat / checklist check-off / day review

ChatPlan loop (external AI)

• POST /api/plan/{day}/import — ChatPlan JSON (or {plan, mode}) → timetable
• GET /api/plan/{day}/export — filled ChatPlan in envelope
• GET /api/plan/{day}/export.txt — downloadable JSON attachment
• POST /api/plan/{day}/blocks/{id}/check — fast status without thick feedback
• PATCH /api/plan/{day}/meta — title / intention / constraints / day_review
• Feedback additive: emotions[], fse_event, intensity

Reschedule

• OpenRouter returns JSON blocks; P0 times preserved.
• Without API key / parse fail → rules_backup_reschedule.
• Cooldown RESCHEDULE_MIN_GAP_MIN unless force.