Obligations#
An obligation is the unit of work in Remindify. It replaces the loose reminder with a record that has an owner, a backup, a deadline, a risk score and a proof requirement.
Anatomy#
| Field | Type | Notes |
|---|---|---|
id |
string | Server-assigned (ob_...). |
title |
string | Required. Trimmed to 140 characters. |
category |
string | people, health, identity, finance, work, home or other. |
provider |
string | Who the work is with. Defaults to Unassigned. |
owner, backup |
string | The person responsible and the person who notices when they don't. |
amount, currency |
number, string | Money at stake. Defaults to 0 and USD. |
due_at |
ISO 8601 | Defaults to 14 days from creation when omitted. |
recurrence |
object or null |
{ "unit": "day" | "week" | "month" | "quarter" | "year", "interval": 1 }. |
autonomy |
string | notify, prepare, approve or autopilot. Defaults to prepare. |
severity |
1–5 | Consequence if it slips. Defaults to 3. |
confidence |
0.4–1 | How certain the due date and scope are. Defaults to 0.8. |
proof_required |
string | What must be filed before completion counts. Defaults to Confirmation. |
grace_days |
number | Slack before lateness is real. Defaults to 0. |
checklist |
string[] | Optional steps shown in the drawer. |
status |
string | active until completed; one-off obligations become done. |
Completion also records last_completed_at, completions, last_proof and last_note, which are returned on the next read.
Risk#
Risk is computed when an obligation is read, not stored. The current model multiplies:
- severity (1–5),
- urgency derived from days until due,
- the autonomy factor — less human oversight means more residual risk,
- and a confidence adjustment.
The result is clamped to 2–97 and mapped to a band:
| Score | Band |
|---|---|
| 75–97 | critical |
| 50–74 | high |
| 28–49 | guarded |
| 2–27 | low |
Changing autonomy changes the score immediately. That is intentional: moving from notify to autopilot should look like a decision, not a setting.
Agents can read the portfolio view at GET /api/v1/risk:
{
"coverage": 0.86,
"exposure_usd": 4820,
"counts": { "critical": 2, "high": 5, "pending_approvals": 3 },
"top_risks": [
{ "id": "ob_payroll", "title": "Payroll tax filing", "risk": { "score": 88, "band": "critical" }, "penalty": 240 }
]
}Autonomy#
The ladder is ordered:
| Level | Behaviour |
|---|---|
notify |
Remind the owner. Nothing else. |
prepare |
Draft the plan, checklist and message. Wait. |
approve |
Do the work after a human approves the specific run. |
autopilot |
Do the work automatically, within the connector and ceiling. |
An obligation's autonomy is capped by the agent's autonomy_ceiling. A prepare agent cannot run an autopilot obligation, even if a human sets it.
Autonomy also changes the risk score. Use approve or autopilot only when the proof requirement and the connector make the result checkable.
Completion#
POST /api/v1/obligations/:id/complete with { "proof": "...", "note": "..." }:
- Files a proof receipt in the trust layer, hashed and unsigned.
- For a recurring obligation, advances
due_atby the recurrence and incrementscompletions. - For a one-off, sets
status: "done"and returnsarchived: true. - Records a
proofevent attributed to the caller.
Completion without proof is possible for a human in the app, but agents should always send a reference: what was filed, where it lives, and the identifier a human could check.
Creating obligations well#
- One obligation, one outcome. "Renew the domain" is an obligation. "Do the website" is a project.
- Set the proof before delegating. A connector that returns a receipt reference is more useful than one that says "done".
- Prefer
approvefor irreversible work. Payments, filings and anything sent to a regulator deserve a human yes. - Use recurrence instead of duplicates. Monthly rent is one row with
interval: 1, not twelve rows. - Keep
due_athonest. The parser and the risk score both depend on it.