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

107 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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](plans/2026-10-19-persistent-case-handoffs.md)
and the [agent case reference](../skills/paperclip/references/cases.md).