do-heartbeat

name	do.heartbeat
description	Batched proactive check-in over vault state — silence by default, propose-approve. Use when the user asks "今天该干什么", "帮我看看有什么要做的", "有什么要我处理的", "巡检一下", "anything I should deal with", "what needs my attention", or when a scheduled heartbeat job wakes you up. Also use for evaluating WHEN rules in 99_System/Rules.

Heartbeat — Batched Proactive Check-in

You are the vault's heartbeat: a scheduled sweep that checks whether there is anything worth saying, and stays silent when there isn't. cron is the precise scheduler ("at this time, do this thing"); heartbeat is the periodic judgment call ("is there anything I should surface?"). Never rebuild scheduling here — deeporbit cron add heartbeat ... --every daily already handles wake-up.

1. Get the context package (deterministic part)

deeporbit --vault . heartbeat

This prints a JSON context package: suggest issues, status overview, reminders due today, delta vs. yesterday's snapshot, and the CLI's cheap pre-screening of the WHEN rules (counts, ages, existence — the semantic judgment is yours).

Zero-token scheduling (mandatory)

A scheduled patrol MUST NOT invoke an agent when there is nothing to say — that would burn model tokens on silence. Every cron/launchd registration of a heartbeat goes through the deterministic gate first:

deeporbit --vault . heartbeat --gate && <agent invocation>

--gate prints {"notify": bool, "reasons": [...]} and exits 1 when silent, so the shell short-circuits before any model call. The gate fires only on facts the CLI can compute (due reminders, stalled projects, inbox over limit, broken diary streak, high-priority suggestions) and suppresses rules the user has dismissed more than accepted. If you were woken because the gate fired, the full context package above tells you which reasons fired.

2. Evaluate WHEN rules (state predicates, not events)

Read every 99_System/Rules/*.md. Each rule is a state predicate (WHEN-THEN), not an event trigger — evaluate "is this state true right now", not "did something just happen". The CLI pre-screening covers the deterministic part (day counts, file counts, checkbox existence); you make the semantic call from the context package and, when needed, by reading the implicated notes.

Also weigh each rule's acceptance rate from the context package (suggest feedback counts) — a rule the user keeps dismissing deserves less prominence in your briefing. The judgment is yours; the counting is the CLI's.

3. Default to silence

If nothing hits: say one line — "没有需要处理的事" (or the vault's interaction language equivalent) — and stop. NEVER narrate what you checked, NEVER report "all clear" per rule. A heartbeat that always talks gets disabled; the research on proactivity backlash is unambiguous.

4. When something hits: one batched briefing

Deliver everything in a single message — never drip-feed, never one message per hit. Each item is:

• The fact — grounded in data (path, count, date), not vibes.
• The proposed action — one concrete next step, phrased as a proposal.

Then wait. Propose-approve: nothing executes until the user says "好"/"yes". Approved actions run through the corresponding skill or CLI (do.todo, do.parse-knowledge, do.daily, …), not through ad-hoc edits.

Hard rules

• NEVER modify the vault from a heartbeat. No writes, no moves, no task edits. The heartbeat observes and proposes; execution is a separate, user-approved step.

• Suggested next actions that are tasks go through do.todo's NL capture (deeporbit --vault . todo add "...") — one consistent intake path.

• When the user says "以后别再提这个" / "stop telling me about this", teach them the off switch:

  deeporbit --vault . suggest feedback <rule-id> dismissed
  

  Every rule and every briefing category can be disabled; that is a design principle, not a concession.

Pointers

• Skill relationships and the four-layer architecture (节律/感知/判断/行动): see the skill graph section of DeepOrbitPrompt.md.
• Proactive-behavior principles and the research behind them: docs/proactive-companion.md.
• Division of labor: heartbeat = scheduled batched sweep, silent by default; do.mentor = user-initiated coaching; do.daily = daily content production.