sg-deadline

Deterministic legal deadline computation for Singapore. Rules are data, every answer comes with a derivation trace, and the engine refuses to guess when it lacks holiday data.

Ships as a Python library, a CLI, and an MCP server so AI assistants can call the arithmetic instead of attempting it.

$ sg-deadline compute sg.roc2021.defence 2026-03-13

rule sg.roc2021.defence: Defence to be filed and served (statement of claim served in Singapore)
source: Rules of Court 2021, O 6 r 7
trigger date: 2026-03-13 (Fri)
period: 21 days, direction: after
calendar-day count: 2026-03-13 (Fri) + 21 days = 2026-04-03 (Fri)
2026-04-03 (Fri) is a public holiday (Good Friday): rolled forward to next working day 2026-04-06 (Mon)
DEADLINE: 2026-04-06 (Mon)
holiday data SG 2026: UNVERIFIED, source=Ministry of Manpower gazetted public holidays 2026 (via data.gov.sg), retrieved=2026-09-12

Why this exists

Deadline calculators are a SaaS category (LawToolbox, CourtDeadlines, Esquire). None are open source, none cover Singapore, and none are callable by an AI assistant. Meanwhile LLMs are routinely asked "when is the defence due?" and routinely get it wrong, because date arithmetic with holiday exclusions is exactly the kind of thing language models fumble.

The fix is not a smarter prompt. It is to make the arithmetic deterministic, put it behind a tool, and make the tool show its working.

Related MCP server: jp-business-calendar-mcp

What it computes

Distribution reliability

python -m pip install . installs the CLI with its bundled data, without requiring an editable checkout. Run it from any directory. Source contributors continue to edit the canonical root data directories; the build copies those files into the wheel. No legal facts or verification flags are changed by packaging.

After installing .[dev], run python scripts/check_install.py. It builds a source distribution, builds a wheel from that archive, installs it in a temporary environment outside the checkout, and checks the public commands against the bundled resources. CI runs this check on Linux and Windows. The check installs build tools, but the calculation commands themselves make no network requests.

Install

pip install -e ".[dev]"       # library + CLI + tests
pip install -e ".[mcp]"       # adds the MCP server

Python 3.11+.

CLI

sg-deadline rules                                          # list every rule, flagging unverified ones
sg-deadline compute sg.roc2021.defence 2026-03-13          # trace to stdout
sg-deadline --json compute sg.roc2021.defence 2026-03-13   # machine-readable
sg-deadline limitation sg.limitation.contract 2020-03-15
sg-deadline working-days 2026-12-23 2026-12-31
sg-deadline add-working-days 2026-12-24 3
sg-deadline deemed email 2026-03-13T18:05 --offset 1 --business-days --cutoff 17:00

Exit codes: 0 ok, 2 unknown rule, 3 holiday data missing for a year needed by working-day arithmetic.

Limitation anniversaries do not roll forward. They can therefore be computed beyond the bundled holiday years; the trace and warnings explicitly say when holiday/working-day status could not be checked. This does not verify accrual, the applicable limitation rule or legal exceptions, and it does not relax coverage requirements for procedural or contractual business-day calculations.

MCP server

{
  "mcpServers": {
    "sg-deadline": {
      "command": "sg-deadline-mcp"
    }
  }
}

The server instructs the assistant to call list_rules first and pick a rule id explicitly, so the choice of rule is visible in the transcript, not buried in the model's reasoning. Every tool returns the full trace; the assistant should show it.

Library

from datetime import date
from sg_deadline import load_calendar, load_rules, compute

cal = load_calendar("SG")
rules = load_rules()
result = compute(rules["sg.roc2021.defence"], date(2026, 3, 13), cal)
print(result.deadline)        # 2026-04-06
print("\n".join(result.trace))

Rules are data

# rules/sg/roc2021.yaml
- id: sg.roc2021.defence
  source: "Rules of Court 2021, O 6 r 7"
  description: "Defence to be filed and served"
  period: { days: 21 }
  direction: after
  verified: false
  notes:
    - "Trigger is the date of service of the statement of claim."

Adding a rule is a YAML edit and a golden test. It never requires a Python change.

Every rule carries verified: false until a human has checked the period and provision against the current text on Singapore Statutes Online and recorded the check in notes. Unverified rules still compute, but emit a warning that is returned to the caller and printed to stderr. Do not flip verified to true in a PR without citing what you checked and when.

Everything bundled in v0.1.0 is currently unverified. Progress is tracked in #1, which lists every rule, the provision to check it against, and the two conventions (backward roll for before periods, the limitation anniversary rule) that need a decision rather than a lookup.

Computation-of-time semantics (O 3 r 2)

Months and years use calendar arithmetic (Interpretation Act s 2); where the corresponding date does not exist, the last day of the month is used and the trace says so.

Holiday data

data/holidays/sg-<year>.json, one file per year, sourced from MOM via data.gov.sg. The engine raises HolidayDataMissingError the moment a computation touches a year with no file. This is intentional: a deadline engine that silently treats a public holiday as a working day is worse than one that refuses to answer.

Refresh with python scripts/refresh_holidays.py <year> <dataset_id>; the file stays verified: false until a human compares it to the gazette and re-runs with --verified.

Scope and honesty

• This is a calculation aid, not legal advice. Every output carries the rule reference so it can be checked against the source. Check it.

• Court directions, consent orders and extensions override the default periods and are not modelled. The trigger date you supply must already reflect them.

• Limitation extensions (disability, fraud, acknowledgement, s 24A discretion) are not modelled; the trace says so.

• Only Singapore is bundled. The rules/<jurisdiction>/ and data/holidays/<jur>-<year> layout is designed so other jurisdictions drop in without touching the engine.

Contributing

Read CLAUDE.md for the engineering conventions (they apply to humans too). Short version: rules in YAML, every rule change comes with a golden test computed by hand, no network calls at compute time, never delete a trace line.

Related projects

This engine is consumed by oblig-register (contract obligations to calendar) and is designed to sit alongside citecheck, bundlebuild, chronology and playbook-as-code.

License

MIT.

Calendars that stay up to date

There is no fixed end year in the engine. Application entry points prepare calendars from the official MOM collection on data.gov.sg, discover newly published years and cache source bytes plus immutable calendar snapshots. Arithmetic functions remain pure: callers that use compute() directly still supply a calendar explicitly.

The CLI, MCP tools and skill adapter check missing calendars before calculation and refresh used snapshots when their seven-day check is due. They retain unverified-rule and calendar warnings. Network failure can use existing snapshots with a warning; uncovered or unpublished years cannot produce working-day results. This does not predict future holidays or establish that a legal rule is current.

sg-deadline calendars status
sg-deadline calendars refresh
sg-deadline --receipt matter-date.json --json compute sg.roc2021.defence 2027-01-16
sg-deadline --replay matter-date.json --json compute sg.roc2021.defence 2027-01-16
sg-deadline --offline --json compute sg.roc2021.defence 2027-01-16

Use --calendar-cache PATH or SG_DEADLINE_CACHE for the cache location. Installed skills use their workspace's .legal-eng/calendars; standalone tools default to the user cache. Every application calculation saves an immutable receipt with the exact rule/input identity, engine version and normalized calendars. Raw downloaded evidence is content-addressed in the cache. Copy an explicit receipt into the matter evidence for portable offline replay; keep the original engine installation too. Refresh does not rewrite receipts. A changed-year notice means outstanding dates need review.

The official collection and dataset responses are checked for publisher, membership, complete record counts, duplicate dates and inconsistent weekdays. Structural validation and HTTPS provenance are separate from human legal verification. Automatic downloads never set verified: true. The source data is provided under the Singapore Open Data Licence; its source URLs and hashes are retained with each downloaded snapshot.

The Official calendar availability GitHub workflow refreshes public calendars weekly and retains source snapshots as an artifact. Runtime refresh also works independently of CI. For an offline installation, schedule sg-deadline calendars refresh in its own environment when connectivity is available. A denied request, changed source format or unavailable publisher is surfaced explicitly and never treated as an empty calendar.