Concepts · Planning

Commitments

A task is done once. A commitment comes due again and again, or once by a date, and is due by a time, with proof: three news posts every day by 9am; the newsletter and its video every Thursday. Esy checks the proof itself and is firm about it. In os.esy.com this is the critical checklist on Today, and the score board on Home.

The three cadences

Cadence	Due	Example
`daily`	Every day	One Instagram post for the newsletter, by noon
`weekly`	Every week on its weekday; its steps can fall on the days before	The issue and its video, Thursdays
`once`	One time, by a date (dueDate)	Send the client the agreement by Wednesday

Items: the steps, each with a deadline and proof

A commitment is a list of items. Each one says when it’s due and how Esy knows it happened.

Field	Means
`label`	The step, in words.
`dayOffset`	Days before the due day, 0 to −6. A daily commitment’s items are all 0.
`at`	A wall-clock time in the commitment’s zone ("07:00"), or none for the end of that day. Daylight saving never moves it.
`proof`	Where Esy looks: news_feed, issue_sent, youtube, or manual.

a weekly commitment with steps across the weekjsonc

{
  "title": "The issue and its video",
  "cadence": "weekly",
  "weekday": 3,                      // Thursday (0 = Monday)
  "timezone": "America/New_York",
  "items": [
    { "label": "Tutorial written",  "dayOffset": -5, "at": "17:00", "proof": "manual" },
    { "label": "Roundup locked",    "dayOffset": -1, "at": "15:00", "proof": "manual" },
    { "label": "Video live",        "dayOffset": 0,  "at": "06:00", "proof": "youtube" },
    { "label": "Issue sent",        "dayOffset": 0,  "at": "06:00", "proof": "issue_sent" }
  ]
}

Proof

Proof	Done when	Notes
`news_feed`	A post in the feed was published that day	The day’s posts fill the news items in deadline order. News can’t be ticked by hand: the feed shows whether a post is live.
`issue_sent`	An issue’s email went out that week	Read from the send record.
`youtube`	A video was published through Esy that week	A video uploaded straight to YouTube can be marked done by hand.
`manual`	You marked it done	The record says so.

If Esy can’t read a source just now, the item is unknown, not late, and the day is never called missed on a guess.

How a day ends

Status	When
open	Not settled yet.
met	Every counted item is done. Each item says whether it beat its deadline; a late item done later still turns the day met, not on time.
missed	The last deadline passed without every item done.
excused	You gave a reason. It stays on the record.

A sweep settles each commitment’s current day, and the day before, every ten minutes, whether or not anyone opens the page. Firm: a missed day stays at the top of Today and Home until it’s done or excused.

The chain and the score

Esy counts all of it from how each day ended; the page only shows the numbers.

	Rule
A run	Days (or weeks) kept in a row. A met day grows it, late or not. An excused day or a rest day holds it. A missed day breaks it. Today counts once it’s kept.
Rest days	Two a calendar month per organization, on daily items, taken on the day itself. A rest day holds the run without growing it, and can be taken back.
A perfect day	Every daily item due that day kept or rested, and at least one kept.
Points	10 for a kept daily day, 30 for a kept week, 40 for a once item; half when late. A level every 400 points.
Badges	Seven in a row, a perfect day, a month of weeks, a perfect week, thirty in a row.

Starting fresh

startsOn is the first day a commitment counts. No day before it is judged, and days already on record before it don’t count toward the run, the score or the history. A step due before it (a weekly item’s early steps in its first week) has the state skipped: the page says “before your start”, it’s never late, and it isn’t counted in “2 of 6 so far”.

A commitment is not a big task

If it repeats and missing it matters, it’s a commitment. If it happens once and you’ll know when it’s done, it’s a task. A once item sits between them: a deadline you can’t let slip, with its own countdown.

Reference: Commitments API. How it fits with goals and tasks: The planner.

In short

Daily, weekly or once; each item has a deadline and a proof source.
Esy checks the proof and settles each day; a miss stays until it’s done or excused.
Runs, rest days, points and badges are counted by Esy from the record.
startsOn gives a fresh start: nothing before it is judged.