mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-27 11:20:42 +01:00
a3675ddcdff1a6ff66dcb28fa7b295d0a491eed8
1
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 DottaandPaperclip
|
13a83dd68a |
docs: require sleep-aware background work in reviews (#17138)
## Thinking Path
> - Paperclip manages agents in instances that can be idle between
tasks.
> - Recurring empty database and network checks can keep idle instances
and databases awake.
> - Worker migrations already use events, transaction-aware signals, and
shared deadlines.
> - New features can still add idle scans unless contributors and code
reviewers share an explicit rule.
> - This PR makes that rule discoverable through the repository rule
loader and Greptile.
> - The rule applies to added or expanded behavior without requiring
unrelated legacy polling to be removed.
## Linked Issues or Issue Description
Refs #15625, #17000, #17094, #17106, and #17129.
**Current behavior**
The repository has module ownership and runtime dependency rules, but no
explicit review requirement against new idle polling. A new duty in a
heartbeat tick can undo the benefits of previous worker migrations.
**Proposed behavior**
Require events for changed state, transaction-aware signals for
database-produced work, and shared scheduling for real deadlines. Reject
recurring empty scans, including scans disguised as scheduler callbacks.
Review narrow polling exceptions against concrete obligations and sleep
impact.
**Reason and benefit**
Make sleep-aware design a default review expectation. Preserve delivery,
ambiguous-commit recovery, drain/resume, and external wake correctness
while preventing new permanent idle traffic. Existing unrelated polling
stays outside the requested change.
## What Changed
- Add rules/sleep-aware-background-work.mdc for server, database,
adapter, plugin, and runner background paths, including
server/src/index.ts.
- Require concrete triggers, pending-work predicates, quiet conditions,
actual deadlines, and lifecycle evidence.
- Describe narrow exceptions for active operations and external sources,
with required scope, stop conditions, and sleep limitations.
- Distinguish in-process scheduling from durable Cloud wake coverage.
- Register the matching scopes in .greptile/files.json and link the rule
from rules/README.md.
- Reuse the existing module-boundary rule for ownership instead of
duplicating provider policy.
## Verification
- Passed: JSON parsing, required rule metadata, exact parity between
frontmatter globs and Greptile scopes, and all repository links.
- Passed: 15 representative path matches, including server startup,
nested service workers, producer routes, tests, database signals,
adapters, plugins, and both runner source trees. UI, CLI, docs, and
workflow paths remain outside this rule's glob scope.
- Passed: git diff --check.
- Manually checked contrasting review cases: reject a new empty queue
interval; reject an always-rescheduled empty scan; allow an actual retry
deadline; allow a bounded active readiness probe with lifecycle cleanup;
leave untouched legacy loops alone; reject sleep approval based only on
an internal timer.
- No runtime code changed. Application builds and tests were not rerun
for this rules-only change. This validates rule structure and intended
interpretation, not future reviewer compliance or deployed sleep.
- Greptile: 5/5 on
|