docs(source-control): point babysit-prs cadence cross-references at loop.md §5.3

[kyle-sexton]

This was generated by AI during an autonomous work-loop execution session.

Closes #653

Summary

babysit-prs's SKILL.md described a cadence-ownership split that no longer exists.

#652 added the engine-backed recommended_cadence → ScheduleWakeup.delaySeconds mapping table to
reference/loop.md §5.3, alongside the static Python-free degrade ladder already living there.
reference/cadence.md owns only the cadence states and thresholds — and has said so since #322
("loop.md owns the wake mechanics, this file owns the states and thresholds behind the
recommendation"). SKILL.md still routed readers the old way:

Surface	Before	After
Runbook step 9	recommended_cadence per cadence.md; loop.md §5.3 named only as the "static ladder … Python-free degrade"	Schedule the next wake per the cadence contract in reference/loop.md §5.3.
Reporting closing line	"Recommend the exact next interval per cadence.md"	same sentence, now citing loop.md §5.3
References entry for loop.md	"…checklist, static cadence ladder"	"…checklist, and the §5.3 cadence contract"
Step-5 progressive-disclosure trigger	load cadence.md "only before recommending cadence"	load cadence.md "only before interpreting a cadence state"

The filed issue named step 9. The other three are the same defect: leaving them would have made the
file internally inconsistent about which section owns the seconds.

The Reporting line was a live wrong-number risk, not just imprecision. cadence.md states
idle = daily; §5.3 documents ScheduleWakeup clamping delaySeconds to [60, 3600], so
inside /loop idle and quiet both wake hourly. "Recommend the exact next interval per
cadence.md" could therefore surface an interval the loop will never schedule.

The cadence.md link is dropped from step 9 rather than kept alongside loop.md: §5.3 already
hops to cadence.md for the states in one line, so a second pointer here is the gratuitous
cross-reference CLAUDE.md's pointer-not-copy rule forbids. cadence.md keeps its own References
entry and its step-5 disclosure trigger. The new step-9 wording matches vocabulary the file already
uses at its Step 7 checklist line ("schedule the next wake per the cadence contract (§5.3)") and in
the sibling babysit-loop SKILL.md ("that mapping owns the seconds").

Docs-only. No behavior change, no script or engine change. source-control 0.26.1 → 0.26.2
with the matching CHANGELOG entry.

Test plan

Every command below was run from the branch worktree; all passed.

• plugins/skill-quality/scripts/check-skill.sh babysit-prs (CHECK_SKILL_BASE_REF=origin/main) —
  exit 0, PASS — 0 errors. This is the gate CI runs via scripts/check-changed-skills.sh.
  Includes the 500-line hard cap, all 9 base-ref trigger phrases preserved, broken-internal-ref
  check, and scripts/engine.test.sh.
  • SKILL.md is now 497 lines (base origin/main: 499). An intermediate revision of this branch
    landed at exactly 500 and failed the hard cap (LINE_COUNT >= LINE_HARD_CAP, cap 500) — caught
    by an independent reviewer before the PR was opened. Collapsing step 9 to a single pointer and the
    References bullet back to two lines both fixed the cap and made the diff better follow
    pointer-not-copy. The one remaining WARN is the pre-existing 200-line soft target, untouched by
    this change.
• scripts/check-changelog-parity.sh --check — exit 0.
• scripts/check-changelog-parity.sh --check-bump origin/main — exit 0 (the manifest bump has a
  matching ## [0.26.2] entry).
• markdownlint-cli2 over both changed markdown files, repo config auto-discovered — exit 0,
  0 errors.
• jq empty on plugins/source-control/.claude-plugin/plugin.json — exit 0.
• typos over both changed markdown files — exit 0.
• Every relative link in the edited regions resolved by hand (reference/loop.md, cadence.md,
  safety.md, orchestration.md, freshness.md, stuck-checks.md, feedback.md,
  review-trigger.md); the §5.3 anchor exists at reference/loop.md:426. No external URLs
  introduced, so lychee's absence changes nothing.
• Repo-wide grep for any remaining reference sending a reader to cadence.md for wake seconds, or
  describing §5.3 as holding only the static ladder — none remain. The four surviving cadence.md
  citations in plugins/source-control/ were each checked and are correct.

Claims verified against the actual files rather than the issue text: §5.3 does contain both the
mapping table (loop.md:435-440) and the degrade ladder (loop.md:456-462); cadence.md:4-5 does
disclaim the wake mechanics; cadence.md:27 does state idle = daily against loop.md:449-452's
[60, 3600] clamp. The CHANGELOG entry's causal account was corrected after git show --stat e9cef6e1 showed #652 never touched cadence.md, and git log -L4,5 dated that file's disclaimer to
fe78acb6 (#322) — so the references were always imprecise; #652 only made the correct target
concrete.

Per this repo's fresh-docs mandate, https://code.claude.com/docs/en/skills was fetched this
session. It confirms the progressive-disclosure model this diff operates on — SKILL.md body plus
bundled supporting files loaded on demand — and imposes no constraint on how a SKILL.md cites its
own reference/ files, so the choice of pointer is a repo-convention question, decided above by
CLAUDE.md's pointer-not-copy rule.

Related

• Refs fix(source-control): map babysit recommended_cadence to ScheduleWakeup.delaySeconds #652 / source-control:babysit-prs + loop: dynamic /loop wakeups ignore the engine's own recommended_cadence field #504 — the PR and issue that added the §5.3 mapping table this diff points at.
• Refs feat(source-control): converge babysit-prs tiers + engine (0.8.0) #322 — where reference/cadence.md first disclaimed ownership of the wake mechanics.
• Version note: open PRs feat(source-control): bind babysit guard semantics to an executable contract #1285 and fix(source-control): emit a readiness verdict on the gate's silent failure paths #1264 both claim source-control 0.27.0. If either merges
  first this branch's 0.26.2 becomes a regression — it self-surfaces as a git conflict on both the
  manifest line and the CHANGELOG insert point, so rebase rather than force-merge.

🤖 Generated with Claude Code

[claude]

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

---

PR Review

• Gather context and understand the request
• Read changed files and diff
• Verify claims in PR description against actual file content
• Review CHANGELOG and version bump
• Post review findings

---

Verdict: Approve. All factual claims in the PR description check out against the files on this branch. The fix is correct, appropriately scoped, and internally consistent.

Verified claims

Claim	Checked	Result
loop.md §5.3 header is at line 426	grep -n "## 5.3" reference/loop.md	✅ Line 426
cadence.md disclaims wake mechanics at lines 4-5	Read lines 1-9	✅ "loop.md owns the wake mechanics, this file owns the states and thresholds"
cadence.md:27 states idle = daily	grep -n "idle" cadence.md	✅ "Idle: daily when there are no watched open PRs"
loop.md:449-452 documents the [60, 3600] clamp	Read loop.md:449-452	✅ "ScheduleWakeup clamps delaySeconds to [60, 3600]"
loop.md:435-440 has the mapping table	Read loop.md:435-440	✅ active/normal/quiet/idle → seconds table
loop.md:456-462 has the degrade ladder	Read loop.md:456-462	✅ Python-free fallback ladder
Step-7 checklist already uses "cadence contract (§5.3)"	grep -n "cadence contract" SKILL.md	✅ Line 356
SKILL.md is 497 lines (under the 500-line hard cap)	wc -l SKILL.md	✅ 497
Remaining 4 cadence.md citations in source-control are correct	grep -rn cadence.md plugins/source-control/	✅ All correct per their roles

Step-5 trigger change

The wording shift from "recommending cadence" to "interpreting a cadence state" is semantically correct: cadence.md tells you what active/quiet/idle means (thresholds, real-elapsed-time detection); it does not tell you how many seconds to pass to ScheduleWakeup. Loading it to interpret a state is right; loading it to get the wake interval is wrong — that's §5.3's job.

Step-9 pointer consolidation

Dropping the direct cadence.md link rather than keeping it alongside loop.md is the right call. loop.md §5.3 already carries its own pointer to cadence.md inline at line 433 ("The states behind each value live in cadence.md"), so a second pointer in step 9 would be a gratuitous cross-reference — exactly what the pointer-not-copy rule prohibits.

Wrong-number risk in the Reporting line

The PR description's description of the live risk is accurate. A model following the old instruction ("Recommend the exact next interval per cadence.md") could surface 86 400 s for idle, which ScheduleWakeup silently clamps to 3 600 s — a 24× discrepancy between what the model reports and what the loop actually schedules. The fix is correct.

CHANGELOG and version bump

• ## [0.26.2] follows the established format (no date on any entry, consistent with all prior headings).
• The entry under ### Fixed accurately describes all four changed locations and calls out the wrong-number risk. No overstatement.
• plugin.json 0.26.1 → 0.26.2 is the right patch increment for a docs-only fix.

Version conflict note

The PR correctly flags that PRs #1285 and #1264 both claim 0.27.0. If either merges first, this branch needs a rebase — the conflict will surface on the manifest line and the CHANGELOG insert point, so it won't be silent. Nothing to act on in this PR, but the merge author should watch for it.

No issues found. The change is clean, the reasoning holds, and the files are consistent.

[claude]

Claude finished @kyle-sexton's task in 55s —— View job

---

Security Review — No findings

• Gather context and understand the request
• Read changed files and diff
• Check for injection surfaces, secrets, auth gaps, GH Actions patterns
• Post security review findings

---

Scope: plugin.json (version bump), CHANGELOG.md (prose entry), SKILL.md (4 line-level cross-reference edits).

This PR is documentation-only. Working through each attack surface in scope:

Surface	Finding
Injection (command / path / template)	None. No shell commands, no ${} interpolation, no executable blocks in any changed file. SKILL.md is AI instruction prose; the edits only swap one internal reference/ pointer for another.
Secrets / tokens / credentials	None present in the diff or in any changed file.
Authorization / access-control	No changes to permission declarations, gate logic, merge criteria, or trust delegation.
GitHub Actions patterns	No workflow files modified. Zero .github/workflows/ changes; no pull_request_target, workflow_run, permissions:, or ${{ github.* }} in run: blocks.
Supply-chain / dependency pins	No dependency files touched. $schema URL in plugin.json is unchanged from before this PR.
plugin.json surface	Only the version field changed (0.26.1 → 0.26.2). No new userConfig keys, no new external URLs, no schema changes.

No security issues found.