Files
PaperClipAI/rules/heartbeat-execution-boundaries.mdc
T
DottaandClaude Fable 5.2 ac114d9479 refactor: cut DEVELOPING.md to a setup and workflow guide (#21670)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - `AGENTS.md` tells every contributor and agent to read
`doc/DEVELOPING.md` for setup, commands, testing, and worktrees
> - That file grew to 5,495 lines. Most of it was notes on how one
subsystem behaves, added one pull request at a time
> - Readers could not find the commands. Agents also read behavior notes
as rules
> - This pull request cuts `doc/DEVELOPING.md` to a 660-line setup and
workflow guide. It moves the subsystem notes to focused docs
> - The benefit is a guide that a person or an agent can read in full,
and a clear place for each kind of note

## Linked Issues or Issue Description

**Issue type**

Outdated or confusing documentation.

**Where is the issue?**

`doc/DEVELOPING.md`

**What's wrong?**

The file was 5,495 lines. It opened with 112 lines about case handoffs
before it reached Prerequisites. Unrelated sections sat below the
"OpenClaw Docker UI One-Command Script" heading. Statements about
current behavior read like policy.

**Suggested fix**

Keep setup, commands, and workflow in `doc/DEVELOPING.md`. Move each
subsystem note to a doc for that subsystem. Add an index.

## What Changed

- `doc/DEVELOPING.md` is now 660 lines: prerequisites, start dev, health
checks, local run, test drive, Docker, instance layout, database,
storage, secrets, worktrees, test commands, Storybook, CLI, and an index
of the other docs.
- 15 new docs hold the moved text without wording changes:
`ci-workflows`, `test-infrastructure`, `worktrees`,
`hot-restart-deploys`, `heartbeat-internals`, `runner-internals`,
`workspace-repositories`, `workspace-storage`,
`skills-and-teams-catalog`, `ui-internals`, `case-handoffs`,
`chat-connector-development`, `instance-configuration`,
`integration-api-notes`, `database-backups`.
- "Publish a branch Storybook" moved to `doc/STORYBOOK-DEPLOYMENT.md`.
The privacy rollout notes moved to `doc/ISSUE-PRIVACY.md`.
- Deleted about 280 lines: the story-by-story Storybook notes, "Agent
Artifact Uploads" (a copy of `doc/AGENT-ARTIFACTS.md`), two pointer-only
sections, "Workspace feature checks (2026-10-09)", and "Chat and task
navigation caching". The test-drive build-lock paragraph is now four
lines.
- Repointed every inbound link and every script or workflow comment that
named a moved section.
- `AGENTS.md` now says where a behavior note goes, so the guide does not
grow again.

## Verification

- A script split the file by line range. It asserts that each of the
5,495 source lines is kept, moved, or dropped exactly one time.
- A link check on every changed Markdown file found 0 missing files and
0 missing anchors.
- `node scripts/check-maps.mjs` passes.
- `node --test .github/scripts/tests/*.test.mjs`: 808 pass, 0 fail.
- `node --check` passes on the three scripts with changed comments.
- `pnpm verify` was not run. This worktree has no installed
dependencies, and the change has no runtime code.

## Risks

- Low risk. The change is documentation and comments only.
- A link to a moved section from outside this repository will land on
the top of `doc/DEVELOPING.md`.
- The new docs are not in the audited prose list in
`.github/scripts/ci-inputs.mjs`. An edit to one of them runs full CI. An
edit to `doc/DEVELOPING.md` does not. This PR does not change that list.

## Model Used

- Claude Fable 5.2 (`claude-fable-5-2`), Claude Code desktop, with tool
use.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [ ] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-14 18:02:27 -06:00

130 lines
8.1 KiB
Plaintext

---
description: Keep heartbeat a clear lifecycle coordinator with cohesive modules, explicit execution authority, and safe resource ownership.
globs: "server/src/services/heartbeat.ts,server/src/services/heartbeat/**,server/src/services/heartbeat-*.ts,server/src/__tests__/heartbeat-*.test.ts"
alwaysApply: false
---
# Heartbeat execution boundaries
## Scope and purpose
This rule covers the heartbeat entry point, its extracted modules,
heartbeat-prefixed sibling services, and heartbeat regression tests. Keep the
code organized so a reader can follow whether work may start, who owns the
execution, and how its outcome and resources settle.
## Folder structure and module responsibilities
`server/src/services/heartbeat.ts` is the public entry point and lifecycle
coordinator. Heartbeat-specific modules and their focused `*.test.ts` tests belong
in `server/src/services/heartbeat/`. Tests that exercise the assembled heartbeat
service also live in `server/src/__tests__/heartbeat-*.test.ts`. Keep these roles
distinct: the entry point should make the lifecycle readable, while modules own
the behavior of a particular phase or domain.
Use these existing boundaries when deciding where a change belongs. Paths below
are relative to `server/src/services/heartbeat/`:
| Modules | Responsibility |
| --- | --- |
| `queue.ts`, `scheduling.ts` | Queue admission, coalescing, and dispatch; timer and monitor scheduling. |
| `run-preparation.ts`, `execution-configuration.ts` | Run context and tool access; effective execution configuration and credentials. |
| `session-preparation.ts`, `run-state.ts` | Session selection and resume preparation; persisted run/session state and retrieval. |
| `workspaces.ts`, `workspace-preparation.ts` | Workspace resolution, reuse, and validation; preparing the selected workspace and acquiring its environment. |
| `environment-selection.ts`, `runtime-selection.ts` | Execution environment policy; selecting or restoring the execution runtime. |
| `runtime-execution.ts` | Dispatching prepared work through the runtime and handling its execution result. |
| `run-completion.ts`, `run-lifecycle.ts` | Success/failure settlement; shared status transitions, events, and completion handoffs. |
| `run-control.ts`, `retries.ts`, `recovery.ts` | Stop and cancellation; retry scheduling; restart recovery and unfinished cleanup. |
| `task-context.ts`, `task-markdown.ts` | Assembling task context and rendering assignment text. |
| `run-output.ts`, `run-log.ts` | Per-run output handling; log formatting, redaction, and payload bounds. |
This is a responsibility map, not an exhaustive API inventory. See the
[developer module map](../doc/heartbeat-internals.md#heartbeat-service-extractions) for
additional modules and implementation context. Update these descriptions when
ownership changes.
## Keep the coordinator from growing back
- Keep `heartbeat.ts` roughly stable or smaller as features are added. Small
wiring and lifecycle-ordering changes belong there; substantial new policy,
preparation, provider handling, or result processing belongs in a module.
Access to convenient local variables is not a reason to add another large
block to the coordinator.
- Extend the existing module that owns the behavior before creating another.
If a new responsibility has no owner, add a clearly named module under
`heartbeat/`. Avoid generic `helpers.ts` or `utils.ts` buckets and a separate
file for every small function.
- When a change would substantially grow the coordinator, extract the affected
responsibility in the same PR, backed by characterization tests. If an extracted
module begins accumulating unrelated responsibilities, split it at a cohesive
boundary too. Moving a large block into another file without clarifying its
contract is not enough.
- Preserve visible lifecycle ordering and resource ownership across extractions.
Keep coupled decisions together when splitting them would obscure correctness;
explain that tradeoff when substantial growth is necessary. Size is a signal
to review the boundary, not a reason to split an otherwise cohesive operation.
- Keep provider protocols and environment mechanics in their adapter/runtime
services. Heartbeat should coordinate through their contracts. Small dispatch
branches are appropriate; backend details should not spread into shared policy.
- Use narrow, typed contracts that make inputs, outcomes, and resource ownership
clear. Avoid passing the whole service closure or a generic mutable context.
Production dependencies should flow from the facade into its modules, without
modules importing the facade back.
## Design principles
- **Execution requires current authority.** Queue acceptance is not permission
to execute indefinitely. Admission and dispatch must respect company scope,
responsible-user authority, budgets, pause/Stop, and task eligibility, including
when these change during preparation. Retries and recovery must not become
alternate paths around those controls.
- **Ownership must be explicit.** Every execution and resource needs an owner,
a lifetime, and a defined handoff or release condition. These contracts must
hold across service instances, cancellation, partial startup, and restart.
Process-local coordination cannot establish authority over another process.
- **Completion has several independent obligations.** A result being accepted,
a provider stopping, a workspace being saved, and cleanup finishing are distinct
facts. Keep enough state to represent them honestly. Do not infer that resources
are safe to destroy or that successor work may start from a terminal status alone.
- **Recovery preserves intent and completed work.** Resume the admitted work
under its recorded execution contract. New configuration belongs to a new
admission decision, not a silent reinterpretation of an existing run. Repair
incomplete persistence or cleanup without repeating already completed provider
work. Automatic recovery should be bounded and safe to retry.
- **Durable state governs competing effects.** Claims and transitions must remain
correct when Stop, completion, and recovery race. A losing operation must respect
the winning outcome. Persist authoritative state before publishing notifications;
notification failures must not change the execution result or duplicate effects.
- **Uncertainty stays visible.** Missing ownership or termination evidence must
remain pending, held, or explicitly failed until reconciled. Preserve recoverable
work through failures. Keep security and sandbox requirements intact rather than
silently choosing a weaker execution path. Optional diagnostics must not prevent
essential settlement.
## Examples and allowed exceptions
- Retrying workspace copy-back after an accepted result is recovery work; it
should not start another provider turn merely to repeat the completed task.
- A shared checkout cache and per-run preparation state have different lifetimes.
Organize them by the ownership they need, rather than making all state local to
whichever factory happens to use it.
- Keep coupled admission or cleanup decisions together when splitting them would
hide their ordering. A large cohesive module can be appropriate. Apply these
principles to new or materially changed behavior without requiring unrelated
restructuring or a generic orchestration framework.
## Verification and review
Test the affected contract through observable behavior, including relevant
cancellation, concurrency, partial-failure, and restart cases. Exercise the public
heartbeat path when a module change could alter lifecycle coordination; use an
assembled-app journey for changes to dispatch, Stop, workspace recovery, or saved
agent files. Assert execution and persisted outcomes, not only helper calls.
Flag changes that give one policy competing owners, hide lifecycle ordering,
weaken execution authority, lose recoverable work, or confuse completion with
resource settlement. Explain the violated principle and the responsible boundary.
Also flag substantial coordinator growth or modules collecting unrelated behavior;
identify the existing owner or cohesive extraction that would keep the code
tractable. Do not freeze current variable names or helper layouts as policy.