Operational Heartbeat

The heartbeat is the control loop that keeps Kevin's wiki, skills, automations, generated surfaces, and agent sessions current without making Kevin manage maintenance state.

Core Rule

The heartbeat has one job: keep the system alive, honest, and searchable. A session finds what it needs with kb, checks live maintenance state when the task touches it, does the requested work, queues durable facts with kb note, regenerates retrieval surfaces after wiki writes, and leaves no hidden process or stale scheduler ambiguity behind. This page is a reference: open it when a task needs the maintenance loop; the boot block in private page carries the rules every session needs. Source: AGENTS.md Start Here; scripts/check-freshness.ts; Scheduling Operating Model

[[SOUL]] defines the agent identity. [[USER]] defines Kevin, with private page owning the expanded USER companion structure. This file defines the operating loop. [[agent-operations-hub]] routes the actual task.

The heartbeat is not a ritual checklist. It is a fail-visible control system. If a task does not need maintenance work, keep moving. If maintenance state changes the task, say so concretely.

What The Heartbeat Controls

Session Boot

A session inside the kevin-wiki repo follows AGENTS.md Start Here. Two of its steps feed this loop:

1. Find pages with kb <words> and read their tops with kb get <name>.
2. Run npm run status, which runs scripts/check-freshness.ts, and report the stale pages, waiting notes and overdue items it lists.

If Kevin asked for maintenance, report freshness before acting. If Kevin asked for unrelated work, do the work and mention only the important maintenance deltas at the end. Startup should inform the task, not displace it.

Live State Comes First

scripts/check-freshness.ts is the maintenance source of truth. Static tables in this file describe intent; they do not override the live state in state.json, automations/, raw sources, local scheduler config, or generated artifacts.

Task Operating Loop

Route each task through this loop:

1. Brain-first - run kb <words> and kb get <name> before answering from memory about people, tools, concepts, projects, decisions, or Kevin preferences. Use qmd query for meaning search and rg for exact strings.
2. Skill-first - if a named or clearly matching skill exists, read its SKILL.md before acting.
3. Capability-first - before choosing a tool, CLI, MCP, or service, use Capability Routing Map and Skill Resolver when the route is non-obvious.
4. Shape-first - for broad wiki work, use Wiki Brain Operating Model before Filing Decision Tree.
5. Execute with proof - produce the artifact, diff, output, screenshot, test result, state write, or log entry that proves the work happened.
6. Compound - update pages, skills, automations, routing, or generated surfaces when the result should help future agents.
7. Close cleanly - validate, report residual risk, and clean up spawned processes.

Aliveness Is Not Prompt Cron

Heartbeat maintains operational truth. The future aliveness layer ranks possible actions from source changes, project state, tasks, reminders, and doctors by urgency, expected value, novelty, confidence, workflow relevance, privacy, and interruption cost. It may run safe deterministic work, emit a structured proposal to private page, request approval, defer, or discard with a receipt. private page is the native review artifact; ordinary findings must not create one conversation or notification each. Repeating a generic “be proactive” model prompt is not aliveness. Source: Discord messages 1526124962484719676, 2026-07-13, and 1527130200620404898, 2026-07-15

Heartbeat may report stale automation/control-plane state. The local Daily Brief control plane and private review surface now exist, but Heartbeat must not simulate automated delivery: proposal-producing workflow research stays inactive until Automation V2 lifecycle, authority, delivery, and approval semantics pass their doctors. Manual/CLI proposal opening is the only proven delivery path today.

Freshness Semantics

Separate freshness output into three buckets:

If a sync fails because auth or a local session is missing, leave the sync freshness stale. Successful automation bookkeeping and successful external collection are different facts.

Cadence Matrix

These jobs have a runner. Everything else in automations/ runs only on demand, and npm run status lists it.

The Codex automations are paused: they fire only while the Codex app runs, and it does not. Source: launchctl print, ps -axo comm, 2026-10-30

Every scheduled run must either apply a durable update or record No durable wiki update needed. A silent run leaves no durable state for future agents.

Durable Automation Contract

A recurring automation is complete only when it:

1. Reads AGENTS.md, wiki/HEARTBEAT.md, automations/<slug>.md, and directly referenced files.
2. Writes outputs/<date>/<slug>/<agent>.md.
3. Applies wiki_targets only when promotion criteria pass.
4. Records No durable wiki update needed when nothing should be promoted.
5. Updates state.json under the correct automation/sync key.
6. Appends wiki/log.md.
7. Runs generated-surface checks when wiki, skills, config, routing, or indexes changed.

See Automation Proof Contract and Scheduling Operating Model for the full run contract.

Every Wiki Write

A wiki-editing turn is not done until:

1. The durable shape follows Wiki Brain Operating Model.
2. The target page location follows Filing Decision Tree.
3. Duplicates, aliases, redirects, and existing related pages were searched when creating or moving pages.
4. New facts have sources.
5. Important entities have useful wikilinks and timeline entries when evidence changed.
6. Compiled truth and timeline separation is preserved.
7. Generated surfaces were regenerated instead of hand-edited.
8. npx tsx scripts/build-index.ts ran.
9. qmd update && qmd embed ran, or the failure is reported.
10. wiki/log.md has an entry.
11. A targeted doctor/check ran when routing, schema, automation, generated packs, or broad graph behavior changed.
12. For broad article/tool/skill/hub quality work, npm run wiki-quality ran and the audit report was inspected.

For URL, repo, post, or raw captures, follow Capture Ingest Protocol end to end.

Every Agent-Config Write

When changing skills, rules, hooks, MCP config, tool rankings, Codex/Cursor/Claude instructions, workflows, or cross-agent presets:

1. Update the executable/config surface.
2. Update the wiki reference page.
3. Update routing pages when behavior changed.
4. Regenerate the skill registry, runtime links, slash-command index, or workflow surfaces when relevant.
5. Run bootstrap/sync/doctor checks appropriate to the surface.
6. Rebuild index and qmd.
7. Log the operation.

See Agent Config Write Checklist and Generated Surface Refresh.

Content Backlog Gate

If the session edits or focuses on wiki/career/content-backlog.md, end by surfacing rows not yet Posted. For rows marked Ready to post, route through social-draft, humanizer, and then kevin-voice or slack-voice depending on channel.

End-Of-Turn Hygiene

If you spawned long-running processes, dev servers, test watchers, browser sessions, or automation jobs:

• keep only what Kevin is actively using
• tear down duplicates and hung workers
• do not kill the editor, agent runtime, user shell, or shared MCP servers
• mention any server URL intentionally left running

If no long-running process was spawned, normal judgment is enough. See End Of Turn Hygiene.

Escalation

Escalate when credentials are missing, destructive action is required, production/customer data is at risk, sources conflict, a bulk operation fails its sample, the same command fails twice with the same cause, or an automation is stale because its integration has never been configured.

Escalation should name the blocker and the smallest user action that would unblock it.

---

Timeline

• 2026-11-05 | The Monday harvest row names its runner, the scheduled task kevin-wiki-weekly-harvest (since 2026-11-03), and its steps from the rebuilt spec: it plans unattended and applies after Kevin approves the table. Source: automations/cross-project-learning.md; ~/.claude/scheduled-tasks/kevin-wiki-weekly-harvest/SKILL.md
• 2026-11-04 | Rewrote the page to match the 2026-11-03 boot: sessions load the Mac rules and the working-set card, look pages up with kb, and open this page when a task needs the maintenance loop. Removed the workflow-first step, because the workflow registry was retired on 2026-11-03. Source: AGENTS.md Start Here; Wiki Brain Operating Model
• 2026-10-30 | Replaced the intended cadence matrix with the four jobs that have a runner: the Daily Brief server, the daily wiki-intake launchd job, the Monday cross-project-learning session and the weekly Gmail cleanup. The Codex automations were paused, because the Codex app does not run. Source: wiki overhaul Phase 3, 2026-10-30
• 2026-07-16 | Attached aliveness to the specified Daily Brief control plane, required quiet structured proposal delivery, and prohibited false activation before automation V2 and the native artifact exist. Source: User request; private page
• 2026-07-14 | Added the workflow-first insertion point and separated heartbeat maintenance from a relevance-ranked aliveness/Daily Brief layer; generic proactive prompt cron is explicitly insufficient. private page
• 2026-07-14 | Removed the retired offsites and Hawaii planning jobs from the daily cadence. private page
• 2026-07-01 | Rebuilt the heartbeat as the current control loop for identity boot, live freshness state, sub-daily ingest, durable automation proof, wiki/config closeout, generated-surface refresh, and process hygiene. private page
• 2026-07-01 | Aligned the heartbeat wiki-write loop with the updated Agent Soul and Wiki Brain Operating Model: shape before filing, generated surfaces in closeout, and broader graph validation when routing or packs change. private page
• 2026-06-30 | Added the sub-daily communications/source loop: Slack sync, Gmail sync, and source compile/X bookmark review should run every four hours with raw digests, durable wiki promotion, ISO state timestamps, and scheduler freshness checks. private page
• 2026-06-28 | Clarified that heartbeat means scheduled work plus durable wiki writeback, added scheduler drift to freshness semantics, and aligned the cadence matrix with the Codex/Cursor automation layer. Source: User request, 2026-06-28; Scheduling Operating Model
• 2026-06-25 | Added npm run wiki-quality to the heartbeat for broad read-first/router/source/skill-load audits, with reports under outputs/audits/. private page
• 2026-06-24 | Added engineering routing to the heartbeat: tool-routing-first behavior, no-sus trigger conditions, repo-local source order, invariant/interface/proof loop, and no-sus review as an on-demand cadence item. Source: User request, 2026-06-24; tool-hierarchy.mdc; Skill Resolver; Security and Review Skills
• 2026-06-24 | Reframed the heartbeat as a compact operating loop: session boot, task routing, freshness semantics, wiki-write/config-write done checks, cadence from live freshness state, and end-of-turn hygiene. Source: User request, 2026-06-24; AGENTS.md; scripts/check-freshness.ts; Agent Operations Hub
• 2026-06-18 | Expanded into an operational cadence with session startup, task routing, daily/weekly/monthly loops, wiki-write checks, config-write checks, content backlog gate, and end-of-turn hygiene. Source: User request, 2026-06-18; AGENTS.md; Agent Operations Hub
• 2026-05-31 | Prior heartbeat recorded the startup trio, freshness check, automation cadence, and wiki-write checklist. Source: AGENTS.md