/ 01What an obligation is
In Ledger, an obligation is a structured representation of a promised action. It has a party who must perform (obligor), a party who benefits (obligee), an action, optionally a deadline, and a status that progresses through a defined lifecycle.
Obligations are extracted from contract text. They are not the same as issues from Review — Review tells you about problems; Ledger tells you about commitments. The same contract can have zero issues and many obligations.
/ 02Modal-verb taxonomy
Every obligation is classified by the modal verb that introduces it. The classification flows through to severity, escalation policy, and reporting.
| Verb | Force | Default severity | Example |
|---|---|---|---|
shall | Mandatory | Major | The Provider shall deliver the Services by the Service Commencement Date. |
must | Mandatory | Major | The Customer must pay within 30 days of receipt. |
should | Recommended | Minor | The Provider should notify the Customer of foreseeable delays. |
may | Permitted | Informational | Either party may terminate by giving 30 days' notice. |
Per-silo policy can override the default severity per verb. will is context-dependent and routed through a secondary classifier.
/ 03Extraction algorithm
Extraction runs over the output of Semantic (Pass 2 of the pipeline), which has already produced deontic-tagged clauses.
Candidate clauses
Every clause with a deontic verb above confidence threshold becomes a candidate.
Negation analysis
The classifier inspects the dependency graph for negation operators in scope. "The Provider shall not disclose..." is a prohibition, not an obligation, and is routed to a separate prohibition extractor.
Party identification
Subject of the modal verb becomes the obligor. Beneficiary identified from dependents and named-entity recognition.
Deadline extraction
Temporal expressions in the same clause are parsed with the dates extractor; relative deadlines ("within 30 days of...") are resolved against the contract's signature date.
Confidence scoring
Composite of deontic confidence, party-resolution confidence, and deadline-parse confidence. Below silo threshold (default 0.65) the obligation is held in a verification queue.
/ 04Lifecycle states
State transitions emit ObligationEvent records with actor, timestamp, old → new state, and free-text notes. The event log is append-only.
/ 05Schema
@dataclass class Obligation: id: str contract_id: str clause_reference: str # "11.3" — source clause obligor: str # party who must perform obligee: str # party who benefits action: str # what must be done deadline: date | None recurrence: str | None # RRULE-style if periodic status: ObligationStatus assignee_id: str | None statutory_basis: str | None modal_verb: str # shall | must | should | may severity: str extraction_confidence: float # 0.0 – 1.0 manually_verified: bool evidence_required: str | None dependency_ids: list[str] # obligations this depends on
/ 06Escalation engine
Overdue obligations are escalated through a configurable multi-tier path. The default policy:
| Days overdue | Tier | Notify |
|---|---|---|
| 0–2 | 1 · Team lead | Assignee + team lead, email + Slack |
| 3–6 | 2 · Manager | Manager added, daily digest |
| 7–13 | 3 · Legal | Legal team CC'd, immediate alert |
| 14+ | 4 · Executive | Exec sponsor; written breach analysis attached |
Financial exposure weighting promotes obligations one tier when monetary value exceeds the silo's exposure_threshold. Per-obligation policies can override the default ladder.
/ 07iCal calendar feed
Every silo exposes a calendar feed at:
The feed is signed with a per-user token in the URL; revoking the token invalidates the feed immediately. Each event is a VEVENT with the obligation ID in UID, so updates from Ledger propagate as updates in the user's calendar rather than duplicate entries.