# Runbook

> Calm, provable payroll. Every number on every page is derived from an
> append-only event log and effective-dated, cited rule snapshots — and can
> be explained, traced, and recomputed. Nothing on a Runbook surface is
> hand-entered narrative: if you see a number, it has lineage.

Runbook (company) / Runbook Payroll (product) — formerly Duly. Prototype stage.

## For AI agents using this app

- The full machine-readable record behind the UI is available at runtime as
  `window.RUNBOOK` — workers, totals, obligations, review items, the
  correction record, the notice case, rule snapshot id and citations.
  It is the same projection the UI renders; the pixels add nothing.
- Every fact carries two clocks: `effective` (true in the world) and
  `recorded` (when the system learned it). Corrections are new events,
  never edits — replaying a period under either clock is supported.
- Rule parameters carry legal citations (statute / agency publication) and
  effective dates. The snapshot id binds every calculation to the exact
  rules that priced it.
- The page uses semantic landmarks (nav, main, footer), a skip link, and
  USWDS-style focus indicators; interactive controls are real buttons with
  aria-expanded state.
- Verify, don't trust: totals reconcile (gross − deductions = net, to the
  penny) and are recomputable from the event log. If your check disagrees
  with a Runbook number, one of us has a bug — and Runbook publishes its work.

## Key documents

- engine/README.md: the deterministic, bitemporal calculation engine
- engine/src/projection.mjs: how the UI object is derived from engine output
- engine/rules/: jurisdiction rule layers with citations (PolicyEngine-style)
- supabase/migrations/: the append-only bitemporal store schema

## Agent surfaces

- **MCP server (shipped): `node mcp/server.mjs`** — stdio MCP exposing
  get_pay_run, explain_number, verify_run (recomputes reconciliation
  identities so you can check the work), get_correction_record,
  get_notice_case, list_rule_citations, get_proof_packet. See mcp/README.md.
- **The Quittance (shipped)**: a canonical, Ed25519-signed proof document
  carrying totals, lineage, the cited rule snapshot, and the full
  replayable event log. Get it via the `get_quittance` MCP tool or
  `node engine/tools/export-quittance.mjs`; verify the seal with
  `verify_quittance` (tamper-evident: changing one penny breaks it), or
  recompute the run from the embedded events yourself.

## Agent authority boundaries

Runbook supports agent-mediated payroll, not AI-calculated payroll.

Allowed now:

- read the machine record;
- verify runs and Quittances;
- explain numbers from lineage;
- draft `runbook.proposals` documents;
- prepare draft run previews;
- surface assertions and refusals for human review.

Not allowed now:

- approve a pay run;
- approve a timecard;
- move money;
- file taxes;
- create or alter `recorded` timestamps;
- publish rule values;
- override engine assertions;
- write directly to production stores without a human confirm surface.

Future delegated approval must be explicit, scoped, revocable, and
recorded as an approval event with delegation evidence. Until that ships,
approval stays human.

## Safe agent workflow

1. Read the current record through the UI projection or MCP.
2. Verify before acting: call `verify_run` or verify a Quittance.
3. Explain any number from lineage before changing facts.
4. Draft changes with `propose_facts` or `draft_correction`.
5. Price the draft with `prepare_run`.
6. Hand the `runbook.proposals` document to the human review surface.
7. The human confirms rows; Runbook records server-stamped events.
8. Only after approval does Runbook seal a Quittance.