fix(source-control): map babysit recommended_cadence to ScheduleWakeup.delaySeconds

[kyle-sexton]

Summary

The babysit-prs snapshot engine computes a recommended_cadence field (reference/cadence.md: active=5m / normal=15m / quiet=1h / idle=1d), and reference/loop.md §5.3 told the orchestrator to "derive the wake interval" from it — but never gave the string-to-seconds translation for a ScheduleWakeup.delaySeconds call. So orchestrators (including the babysit lane itself, historically) silently fell back to the generic /loop skill's own "lean 1200–1800s" fallback-heartbeat range, overriding the domain skill's tighter adaptive-cadence contract. Net effect: PRs with pending CI or blocking feedback sat unchecked 4–5x longer than the skill's own cadence contract intends.

Fix

reference/loop.md §5.3 (engine-backed subsection) now carries:

1. A deterministic recommended_cadence → ScheduleWakeup.delaySeconds mapping table: active→300, normal→900, quiet→3600, idle→3600. The prior duration prose ("active 5 minutes, normal 15 minutes…") is replaced by the seconds table so the mechanics live in one place; cadence.md remains the owner of the states/thresholds behind each value.
2. An explicit idle-ceiling caveat: ScheduleWakeup clamps delaySeconds to [60, 3600] (verified against the tool's live schema — delaySeconds is "Clamped to [60, 3600] by the runtime"), so cadence.md's idle = daily (86400s) truncates to the 3600s ceiling, the same interval as quiet. Documented as a known limitation with a pointer to the durable /schedule cron mechanism for a genuine daily cadence — not left as a silent truncation.
3. A plain statement that the domain skill's recommended_cadence ALWAYS wins over the generic /loop heuristic whenever a snapshot supplies it: in babysit dynamic mode the ScheduleWakeup delay is the primary cadence signal, not a fallback heartbeat behind some other armed wake event — so the generic skill's 1200–1800s heartbeat framing does not apply.

Version bump 0.13.1 → 0.13.2 (patch, behavioral fix) plus a ## [0.13.2] CHANGELOG entry.

Verification

The added §5.3 engine-backed guidance reads:

Engine-backed runs (Python present): the snapshot's recommended_cadence is the cadence signal — map it directly to a concrete ScheduleWakeup.delaySeconds. The states behind each value live in cadence.md; this table owns the seconds:

recommended_cadence	ScheduleWakeup.delaySeconds
active	300
normal	900
quiet	3600
idle	3600 (ceiling — see caveat)

This mapping ALWAYS wins over the generic /loop skill's own delay-picking heuristic whenever a snapshot supplies recommended_cadence. Read the field out of the snapshot/state JSON and schedule from this table — do not fall back to the generic skill's "lean 1200–1800s" range. In babysit dynamic mode the ScheduleWakeup delay is the primary cadence signal, not a fallback heartbeat sitting behind some other armed wake event, so the generic skill's heartbeat framing does not apply here: an active cycle schedules at 300s, never 1200–1800s.

Idle ceiling (a true daily cadence cannot run in single-session /loop). ScheduleWakeup clamps delaySeconds to [60, 3600], so cadence.md's idle = daily (86400s) truncates to the 3600s ceiling — the same wake interval as quiet. This is a documented limitation, not a silent truncation: within /loop, idle and quiet both wake hourly. A genuine daily babysit cadence needs the durable /schedule cron mechanism (a scheduled routine on a real cron interval), not a single-session /loop wakeup — reach for /schedule when that is what is wanted.

Acceptance criteria:

• ✅ Deterministic recommended_cadence → delaySeconds mapping table present.
• ✅ An orchestrator following the doc schedules an active cycle at 300s, not the generic 1200–1800s range (stated explicitly).
• ✅ The idle/daily ceiling limitation is documented with a /schedule-cron pointer, not left as a silent gap.
• ✅ markdownlint-cli2 and typos pass on both changed docs.

Closes #504

Related

• source-control(babysit-prs): SKILL.md step 9 cross-reference to loop.md §5.3 is imprecise after #504's cadence-mapping table landed #653 — post-green review finding (SKILL.md step 9 cross-reference imprecise after this PR), deferred, cosmetic-only

• loops/skills: self-paced /loop idles between non-empty cycles — cadence should be work-state-driven (no delay when queue non-empty), not a guessed clock #500 — the generic sibling (triage lane's "no delay when queue non-empty"). Different skill; reference only, not fixed here.

• source-control:babysit-prs + loop: /loop 15m fires overlap in-flight fan-out cycles when batch-cap-10 dispatch runs long #472 — fixed-interval /loop Nm overlap (a different failure mode). Reference pointer, not fixed.

• source-control(babysit-prs): absorb v4 loop-prompt operating rules into the skill #477 — absorption umbrella (lists pacing-vs-concurrency but not this specific recommended_cadence-consumption gap). Reference pointer, not fixed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KyLj6oaFVTE6xFuoYCC2KC

[claude]

Claude finished @kyle-sexton's task in 1m 49s —— View job

---

Code Review — fix/504-babysit-cadence-mapping

• Gather context and read changed files
• Review reference/loop.md changes
• Review plugin.json version bump
• Review CHANGELOG.md entry
• Post findings

---

Summary

This is a clean, narrowly-scoped documentation fix. The ScheduleWakeup.delaySeconds mapping table is correct, the idle-ceiling limitation is properly disclosed, and the priority rule ("this mapping ALWAYS wins") closes the original gap definitively. No correctness issues; one minor observation noted below.

---

reference/loop.md — Core Change

Mapping table accuracy (verified against cadence.md state definitions):

recommended_cadence	cadence.md prose	Mapped seconds	Correct?
active	every 5 minutes	300	✓
normal	every 15 minutes	900	✓
quiet	hourly	3600	✓
idle	daily (86400s)	3600 (ceiling)	✓ documented

All four values are arithmetically consistent with the source-of-truth descriptions in cadence.md. The ScheduleWakeup [60, 3600] clamp is confirmed by the live tool schema.

Priority statement — the ALWAYS wins phrasing is strong and unambiguous. No orchestrator following §5.3 can reasonably fall back to the generic /loop heuristic after reading this; the original silent override is closed.

Idle-ceiling caveat — the /schedule pointer gives a concrete escape hatch for genuine daily cadences. Documenting it as a known limitation rather than a silent truncation is the right call.

Python-free ladder untouched — the existing degrade table (lines 392–396 in the final file) correctly handles the no-snapshot case and is unaffected by this change. The boundary between "engine-backed" and "Python-free" sections is clear.

Permalink: loop.md §5.3 (new table)

---

Minor Observation (non-blocking)

SKILL.md step 9 phrasing is still accurate but slightly imprecise after this change. It reads:

Schedule the next wake from the snapshot's recommended_cadence (reference/cadence.md); the static ladder in reference/loop.md §5.3 is the Python-free degrade.

After this PR, §5.3 now houses both the engine-backed mapping table and the Python-free ladder. The step 9 reference still works (it correctly points to loop.md §5.3 for the degrade ladder), but it no longer surfaces that §5.3 is also where the engine-backed mapping lives — a reader might still go to cadence.md first looking for the seconds. A future cleanup could tighten this to something like:

Schedule the next wake using the mapping table in loop.md §5.3 (engine-backed) or the static degrade ladder in the same section (Python-free).

This is out of scope for this PR and not a blocker — the existing cross-reference is navigable.

---

plugin.json — Version Bump

0.13.1 → 0.13.2 is correct: patch semver for a behavioral fix with no interface change.

CHANGELOG.md — Entry

Well-written. The entry accurately describes the problem (silent fallback to 1200–1800s), the fix (deterministic table + priority statement), and the idle-ceiling nuance. Format follows the established Keep a Changelog style.

---

Verdict: approved. The fix is correct, internally consistent, and complete. No blocking issues.

[kyle-sexton]

Review classification (work-2 lane, post-green pass)

#	Finding	Classification	Disposition
1	Mapping table correctness, priority statement, idle-ceiling caveat, Python-free ladder boundary	All ✓ verified by review, no findings	N/A
2	SKILL.md step 9's cross-reference to loop.md §5.3 is slightly imprecise now that both the mapping table and degrade ladder live there	VALID, deferred (cosmetic, non-blocking per reviewer's own assessment)	Filed #653, cited in ## Related

Verdict: approved, no blocking issues. Flipping to ready.

[claude]

Claude finished @kyle-sexton's task in 1m 20s —— View job

---

Code Review — fix/504-babysit-cadence-mapping

• Gather context and read changed files
• Review reference/loop.md changes
• Review plugin.json version bump
• Review CHANGELOG.md entry
• Post findings

---

Summary

Clean, narrowly-scoped documentation fix. The mapping table values are arithmetically correct against cadence.md, the priority statement closes the original silent-fallback gap definitively, and the idle ceiling is disclosed rather than truncated silently. No correctness issues found.

---

reference/loop.md — Core Change

Mapping table — verified against cadence.md:

recommended_cadence	cadence.md definition	Mapped seconds	Correct?
active	every 5 minutes	300	✓
normal	every 15 minutes	900	✓
quiet	hourly	3600	✓
idle	daily (86400s)	3600 (ceiling, documented)	✓

All four values are consistent with cadence.md. The ScheduleWakeup [60, 3600] clamp is confirmed by the live tool schema (the delaySeconds description in ScheduleWakeup states "Clamped to [60, 3600] by the runtime").

Priority statement (lines 376–381) — the ALWAYS wins phrasing is strong and unambiguous. No orchestrator following §5.3 can reasonably fall back to the generic /loop heuristic after reading this.

Idle ceiling caveat (lines 383–388) — the /schedule pointer gives a concrete escape hatch for genuine daily cadences. Documenting this as a known limitation rather than a silent truncation is the right call.

Python-free degrade ladder (lines 390–396) — untouched and unaffected. The boundary between "engine-backed" and "Python-free" sections is clear.

cadence.md cross-reference — cadence.md's own preamble ("the loop derives its wake interval from it — loop.md owns the wake mechanics") remains accurate after this change; the ownership language still correctly defers to loop.md.

---

plugin.json — Version Bump

0.13.1 → 0.13.2 is correct: patch semver for a behavioral fix with no interface change.

CHANGELOG.md — Entry

Well-written and accurate. The entry covers the problem (silent fallback to 1200–1800s), the fix (deterministic table + priority statement), and the idle-ceiling nuance. Format follows Keep a Changelog style consistently with prior entries.

---

Previously Noted (Non-Blocking)

SKILL.md step 9's cross-reference to loop.md §5.3 is slightly imprecise now that §5.3 houses both the engine-backed mapping table and the Python-free degrade ladder — a reader looking for the seconds mapping might still go to cadence.md first. Already filed as #653 and cited in ## Related; out of scope for this PR, not a blocker.

---

Verdict: approved. The fix is correct, internally consistent, and complete. No blocking issues.

[claude]

Claude finished @kyle-sexton's task in 2m 24s —— View job

---

Code Review — fix/504-babysit-cadence-mapping

• Gather context and read changed files
• Review reference/loop.md changes
• Review plugin.json version bump
• Review CHANGELOG.md entry
• Post findings

---

Summary

Clean, narrowly-scoped documentation fix. The ScheduleWakeup.delaySeconds mapping table is arithmetically correct against cadence.md, the priority statement definitively closes the silent-fallback gap, and the idle ceiling is properly disclosed. The merge conflict (main advancing to 0.13.3 while this branch bumped from 0.13.1) is resolved correctly by the merge commit — the content is re-homed as [0.13.4]. No correctness issues.

---

reference/loop.md — Core Change

Before / after diff verified (common ancestor 75b7fdb vs current 0cbe3c1). The original engine-backed text was:

derive the wake interval from the snapshot's recommended_cadence — active 5 minutes, normal 15 minutes, quiet hourly, idle daily — per cadence.md's states and thresholds.

That's the exact gap: vague natural-language prose with no concrete seconds, leaving orchestrators to fall back to the generic /loop heuristic's 1200–1800s range. The replacement:

Mapping table accuracy (verified against cadence.md):

recommended_cadence	cadence.md definition	Mapped seconds	Correct?
active	every 5 minutes	300	✓
normal	every 15 minutes	900	✓
quiet	hourly	3600	✓
idle	daily (86400s)	3600 (ceiling, documented)	✓

All four values are arithmetically consistent with cadence.md. The [60, 3600] ScheduleWakeup clamp is confirmed by the live tool schema.

Priority statement (lines 376–381) — the ALWAYS wins phrasing is unambiguous and directly addresses the root cause. An orchestrator following this cannot reasonably fall back to the generic heuristic.

Idle ceiling caveat (lines 383–388) — disclosed as a known limitation with a concrete /schedule escape hatch. Not a silent truncation.

Python-free degrade ladder (lines 390–396) — untouched and correct. Boundary between engine-backed and Python-free sections remains clear.

cadence.md preamble unchanged — its existing loop.md owns the wake mechanics ownership statement remains accurate.

---

Merge Conflict Resolution

The merge commit 0cbe3c1 correctly re-homes this PR's CHANGELOG entry as [0.13.4] on top of main's [0.13.3]. The commit message explains the version conflict precisely: main advanced source-control to 0.13.3 (#651, #666) while this branch bumped from an older 0.13.1 base. No content drift in loop.md between the original fix commit and the merged head.

plugin.json — Version

0.13.4 is correct after re-homing (the original bump was 0.13.1 → 0.13.2, but main's 0.13.2 and 0.13.3 landed first, so 0.13.4 is the right patch increment).

CHANGELOG.md — Entry

Well-written [0.13.4] entry covering the problem (silent fallback to 1200–1800s), the fix (deterministic table + priority statement), and the idle ceiling. Format is consistent with prior Keep a Changelog entries.

---

Previously Noted (Non-Blocking, Deferred as #653)

SKILL.md step 9's cross-reference to loop.md §5.3 is slightly imprecise now that §5.3 houses both the engine-backed mapping table and the Python-free degrade ladder. Already filed and cited in ## Related; out of scope for this PR.

---

Verdict: approved. The fix is correct, internally consistent, and the merge conflict was resolved cleanly. No blocking issues.