docs(hibernation): mark memo as design-stage / unimplemented (#825)

[robotrocketscience]

Summary

docs/design/hibernation_lifecycle.md was a design memo for an unimplemented feature. Per #825 option A (operator decision recorded 2026-05-14T23:54Z): rewrite the doc to current reality rather than implement the eligibility surface (B) or delete the file (C).

What changed

• Status section rewritten with an UNIMPLEMENTED banner that names the empty src/ surface (git grep 'list_hibernated\|hibernate_eligible\|def.*hibernat' src/ returns nothing; hibernation_score is always written as NULL) and instructs readers to treat the rest of the file as design-stage notes, not current behavior.
• Candidate A SQL block replaced with a paragraph noting that the original demotion_pressure-keyed trigger no longer applies (column removed by refactor(feedback): remove unreachable CONTRADICTS-edge auto-demote path (per #605) #814 / PR refactor(feedback): remove unreachable contradict-edge auto-demote (#814) #820) and no replacement signal has been chosen.
• Decision ask updated to mark ratification as deferred until an implementation pass is scheduled.
• <!-- TODO(#825) --> marker dropped — this PR is the disposition.

Acceptance check

The issue acceptance was: "docs/design/hibernation_lifecycle.md contains no claim about behaviour that doesn't exist in src/."

• The Status banner now leads with the gap.
• The 4 remaining demotion_pressure references are all historical context (explaining why each section is unimplemented), not claims that the column or trigger exists. Verified via grep -n 'demotion_pressure' — see commit message.
• No new SQL examples claim to mirror code that doesn't exist.

Pre-push gates

• Discretion grep on git diff main...HEAD → 0 hits.
• Commit message also discretion-clean.
• Single signed commit, FF on current main (5f71d802).
• Doc-only change; no pytest run (no tests touched).

Closes #825.

[sourcery-ai]

Sorry @robotrocketscience, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Warning

Rate limit exceeded

@yoshi280 has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 15 minutes and 50 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 2ad2155e-4fd9-45f6-9289-c319b96f8ce9

📥 Commits

Reviewing files that changed from the base of the PR and between d91c5fc and d3ea7ef.

📒 Files selected for processing (1)

• docs/design/hibernation_lifecycle.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-825-hibernation-doc-reality

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[robotrocketscience]

[claim:review:clarke:2026-05-15T00:11:36Z]

[robotrocketscience]

[release:review:clarke:2026-05-15T00:12:21Z]

[github-actions]

merge-train: blocked

branch is not fast-forward on main (branch base 5f71d80204707a116b36b0fa6e54b22c0e41826b, current main 04a68ba52cb32d78e17a02190c9daba9653667a8). Rebase locally (git rebase github/main), force-push, and re-add the label.

The ready-to-merge label has been removed. Address the issue above and re-add the label when you're ready for another attempt.

[robotrocketscience]

[claim:review:prince:2026-05-15T02:02:43Z]

[robotrocketscience]

Reviewed 7f97e624 (rebased to d3ea7ef5 onto current main d91c5fc2 — clean fast-forward, doc-only file did not conflict with any of #831 / #829 / #836 since those landed). Single signed commit.

AC vs #825:

• Operator decision recorded 2026-05-14T23:55:46Z chose A (rewrite to current reality).
• "§ Candidate A SQL example replaced with prose noting the gap" — confirmed: the trigger block becomes a paragraph that says no SQL trigger of this shape exists in src/.
• "Resulting docs/design/hibernation_lifecycle.md contains no claim about behaviour that doesn't exist in src/" — confirmed: the remaining demotion_pressure references are framed as historical context for why each section is unimplemented, not as claims that the column or trigger exist.
• "<!-- TODO(#825 follow-up) --> marker dropped" — confirmed at the top of Candidate A.
• "Status banner names the empty surface" — confirmed: the banner cites git grep 'list_hibernated|hibernate_eligible|def.*hibernat' src/ returns nothing and git grep 'hibernation_score\s*=' src/ shows only the row→model load and write-NULL paths.

Sanity grep on the live file (post-rebase): zero positive claims that the trigger / grammar / sweeper exist in code. The Decision-ask is correctly demoted to "deferred" pending implementation pass.

Pre-push gates:

• Discretion grep on main...HEAD — clean.
• Signed commit; FF on current main after rebase.
• Doc-only; no pytest gate applies.

Re-adding ready-to-merge.

[robotrocketscience]

[release:review:prince:2026-05-15T02:04:09Z]

[github-actions]

merge-train: merged d3ea7ef → main via FF push.