Files
PaperClipAI/doc/case-handoffs.md
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

7.3 KiB
Raw Blame History

Persistent case handoffs

Developer notes for the Cases experiment: handoff delivery, native case tools, and where the tests live.

The Cases experiment supports prompt-driven agent workflows on one ordinary task. The application service owns transaction/idempotency and assignment policy; case-handoff-delivery.ts owns durable retry/lease and wake admission; heartbeat/case-handoff-lifecycle.ts owns execution release proof and stale-run mutation fencing. Keep network/process work outside the acceptance transaction. heartbeat/process-settlement.ts checks local process-tree absence independently of scratch-directory preparation. A local process handoff stays pending while the owned PID or process group is alive, or termination evidence is missing. HTTP adapters use their awaited nonprocess invocation contract instead of host PID probes. Stopping a run cancels its own intents; cancelling an unbound terminal intent additionally requires fenced, current task ownership. case-context.ts builds the bounded authorized case snapshot shared by native and legacy task preparation, including resumed sessions.

Native case tools are create_case, read_case, update_case, and handoff_case. Native creation requires kickoff and delegates to the same principal-idempotent handoff service. Both kickoff and nonblank workflow_document_text are mandatory; missing either fails before any writes. The text is preserved in ordinary Markdown task document workflow, title Workflow, in the acceptance transaction. New-case handoff API requests require the same field. The workflow plus optional document seeds share a 200,000-character budget; workflow cannot appear in initialDocuments. Later phase handoffs omit the text; normal revision tools manage changes. Read workflow before routing: its reference is prioritized in case context, without injecting its full body. Recommend both a Mermaid stateDiagram-v2 map and prose defining each transition's trigger, evidence, next agent, human wait/resume behavior and correction/escalation limits. State IDs match phase names and prose defines named edge outcomes. This guidance adds no server-enforced transition semantics. There is no passive creation branch or createOnly REST extension. Historical generic REST upsert semantics remain compatible. initialDocuments is valid only for new first-task kickoff; ordinary task documents and audit are committed before delivery. Case detail/context roll up authorized task document metadata through case-task-documents.ts; system keys and inaccessible task documents are excluded before the document limit. Standard task document tools handle new documents; historical case document REST/storage remains intact. read_case keeps small responses structured. Large responses return bounded readPage.text JSON chunks with case/task routing versions on every page. Use section: "fields" to retrieve the entire fields object, including large keys, strings, and arrays. Continue with the same section and snapshot, passing offsetBytes: readPage.nextOffsetBytes until it is null; concatenate the text before parsing JSON. A 409 means facts, accessible references, or routing changed: restart at offset zero without the old snapshot. Each page reauthorizes current case access through GET /api/cases/:id?agentRead=true; no generic API tool or asset grant is needed. limitBytes is 4–8192 UTF-8 bytes. Ordinary REST reads retain their existing full response, and ordinary update_case mutation receipts remain unchanged. Use section: "document" and documentKey for a historical case-owned body; add documentIssueId for a primary or currently linked task document. This selection retains the same bounded JSON paging and does not enable generic API tools. Each page checks current case access, task access, linkage, and document trust. System and quarantined documents are excluded. Document edits and routing changes invalidate the snapshot; restart from zero after a 409. Each page reloads case metadata and the complete selected body to check access and compute its snapshot. These limits bound the response, not total database work; the read cost grows with source size and the number of pages.

Keep native schemas aligned with their services/routes. Transactional source run checks must precede case writes, so Stop or an accepted handoff cannot race an HTTP request into a late mutation. Generic API rollout settings do not remove these dedicated tools; case, mode and resource authorization still apply. Company deletion removes cases before task/agent dependencies. Individual agent purge preserves handoff attribution and returns agent_case_history_retained before destructive cleanup when history references that agent. Termination stays available.

The native constructor preserves full case context for bootstrap and resume failure. Compatible continuations carry a versioned case projection tied to the actual prior native input and exact agent/task/session. Stable facts fingerprints include document revisions and accessible references, while phase/version and incoming instructions are refreshed separately. Do not use a prepared contextSnapshot.paperclipCase as proof that a compact provider turn received those facts. Legacy adapters continue to receive their bounded case snapshot.

Start work through handoff_case or POST /api/companies/:companyId/case-handoffs. Subsequent calls use the same primary task and observed case/task revisions. GET the case's /handoffs for history; /handoffs/:handoffId/retry retries delivery without creating new work, and /cancel cancels pending delivery without reversing an applied assignment. Ordinary task completion leaves the case unchanged. For an existing primary task, to: "done" records a non-yielding terminal handoff; its awaiting_completion intent is settled atomically by the normal issue-service completion transaction. The case remains open during review or user waits. Stop/cancel/reassignment invalidate the intent. Keep terminal intents outside agent-transfer mutation fencing, outgoing yield detection and recipient dispatch.

The board case list/detail pages are read-only. URL query parameters retain search/status/type/project filters through detail navigation; list paging and the GET /api/companies/:companyId/cases/types read use authorized server data. Storybook's Cases / Read-only pages stories mount those same production pages with HTTP fixtures, including document previews, waiting handoffs and mobile.

Cases do not have a quarantine/promotion contract. Low-trust runs must save findings through their governed task/review path rather than write case data. Historical low-trust case provenance also blocks automatic execution context and handoffs; operator reads remain available for review. Skill-test runs omit workflow context to preserve their task-only scope. Cancelled or unapplied handoff intent is history, not an incoming phase instruction.

Focused verification lives in the case route, handoff service, native handoff, durable admission, and legacy process integration tests. Run the explicit-only case-handoffs Product E2E workflow for provider/browser qualification; fixture and service tests do not establish that a live model followed the workflow. See implementation and acceptance and the agent case reference.