State JSON Contract
state.jsonrecords freshness facts for the wiki brain; it is the heartbeat ledger, not a place for agents to hand-wave completion.
Use this page when editing scripts that update state, reviewing stale startup output, or running automations. Kevin should not have to remember what is stale. Agents read state, run the work, then leave proof.
State Families
| Family | Meaning |
|---|---|
automations.<slug> |
Last completed scheduled check for an automation. |
syncs.<source> |
Last successful external collection for Gmail, Slack, Calendar, meetings, X bookmarks, or another integration. |
compile.* |
Source-compile cursors and reviewed bookmark/source state. |
| maintenance keys | Last index, qmd, doctor, self-heal, or other maintenance run recorded by scripts. |
Agents update state through updateState / updateWikiState in maintenance scripts. Do not manually edit timestamps except while repairing the state writer itself.
Integration OAuth tokens and pagination cursors live separately in PGlite at ~/.kevin-wiki/integrations.pglite; Integration Recipes Index owns that setup surface.
Timestamp Rules
Sub-daily jobs must write ISO timestamps. Date-only values are too coarse for four-hour freshness checks. Update syncs.* only after a successful external collection. A blocked automation may update automations.<slug> if it completed the scheduled check and wrote output, but it must leave the corresponding sync key stale.
This distinction matters: "we checked and could not sync" is different from "we synced fresh data."
Proof Contract
State is not sufficient by itself. A completed automation also needs:
- an output artifact under
outputs/when the automation contract calls for one, - a promotion or no-op decision,
- relevant wiki updates when promotion criteria pass,
- a
wiki/log.mdentry.
See Automation Proof Contract for the durable proof model.
Closeout
After changing state semantics or freshness checks, run npx tsx scripts/check-freshness.ts, npm run build-index, and qmd update && qmd embed. If generated pack instructions mention the state key, run npm run agent-packs:refresh.
Timeline
- 2026-07-01 | Expanded state contract with automation vs sync key semantics, ISO sub-daily timestamps, proof requirements, and integration cursor boundaries. Source: User request, 2026-07-01; Operational Heartbeat
- 2026-05-31 | Agent doc formalized from state.json freshness pattern. Source: AGENTS.md, 2026-05-31