0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-07 06:16:06 -10:00

Files

T

History

DottaandClaude Opus 5.5 a4050187ec docs(rules): make upgrade safety part of run and recovery design (#19827 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Native runs save session, checkpoint, lease, and launch state, and
recovery resumes that state later
> - Deploys and restarts often land between the save and the resume, so
one release resumes state that another release saved
> - On 2026-11-06/07, staging deployed four times. Most of 182 failed
runs were saved by one release and resumed by another (#19462, #19659,
#19755)
> - These refusals showed as the generic retryable
`native_session_interrupted`. Retries repeated them, and recovery
replaced a thread (now prevented by #19733). Remote-only code also
shipped without a test that applied Daytona confinement (#19743)
> - This pull request makes upgrade safety a required part of how we
design, fix, and review run and recovery code
> - The benefit is that authors, agents, and Greptile check the release
cutover before a change ships, not after a deploy breaks saved runs

## Linked Issues or Issue Description

Refs #19462, Refs #19516, Refs #19622, Refs #19659, Refs #19733, Refs
#19743, Refs #19755

**Issue type**
Missing contributor guidance for run and recovery code.

**Where is the issue?**
`.agents/skills/fix-failed-paperclip-run/`, `rules/`, `AGENTS.md`, and
`doc/execution-semantics.md`.

**What's wrong?**
No rule or skill step asks how state saved by the previous release is
handled. Fixes added one error code at a time. Saved-identity refusals
used a generic retryable code.

**Suggested fix**
Add a scoped repository rule and additive skill and contract text that
require a previous-release story, permanent named refusal codes, and
cutover tests.

## What Changed

- Add `rules/upgrade-safe-run-state.mdc`. It covers native runtime,
recovery, session preparation, runner, ACPX engine, and sandbox image
paths, and the `packages/db` schema for native run, checkpoint, session,
and run identity state. It requires authors to state how
previous-release state is handled. It requires a permanent, named code
for unknown or changed saved identity, a class-level fix, an
old-saved/new-resumed regression, a deploy-lands-mid-run case where
relevant, and a remote-confinement test for sandbox paths.
- Register the rule in `.greptile/files.json` with the same scope as its
`globs`.
- Link the rule from the "Scoped repository rules" section of
`AGENTS.md`.
- `fix-failed-paperclip-run` skill: step 1 asks if a deploy or restart
separated save from resume, by comparing served revisions. Step 2 asks
this early. Step 4 adds a "Persisted run identity across releases"
safety row and an upgrade-safety paragraph.
- `references/failure-patterns.md`: add "Saved run state meets a
different release".
- `doc/execution-semantics.md`: add §9.4 "Release compatibility of saved
run state".

## Verification

- Docs, skills, and rules only. No product code changes.
- Confirm that each rule glob matches real paths, for example
`server/src/services/native-runtime/`, `server/src/services/recovery/`,
`server/src/services/heartbeat/session-preparation.ts`, and
`packages/adapter-utils/src/acpx-engine/`.
- Confirm that `.greptile/files.json` parses and that its new `scope`
array equals the rule's `globs`.
- `rules/README.md` names no lint check for rules. I did not edit maps,
so `node scripts/check-maps.mjs` does not apply.

## Risks

- Low risk. The change adds guidance only.
- The rule scope includes all of `packages/paperclip-runner/**`.
Greptile can apply the rule to runner docs or UI files. The rule's
exception section says that changes with no persisted shape or identity
need no cutover test.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, with tool use and code
execution in Claude Code.

## 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
- [x] 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
- [x] All Paperclip CI gates are green
- [x] 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 Opus 5.5 <[email protected]>

2026-11-07 08:28:42 -06:00

config.json

docs: track chat channel rules and Greptile configuration (#16172 )

2026-10-13 08:59:27 -05:00

files.json

docs(rules): make upgrade safety part of run and recovery design (#19827 )

2026-11-07 08:28:42 -06:00

README.md

docs: track chat channel rules and Greptile configuration (#16172 )

2026-10-13 08:59:27 -05:00

rules.md

feat(dev): add incremental local verification and pass reuse (#19345 )

2026-11-06 07:29:10 -06:00

README.md

Greptile configuration

This directory tracks the supported review configuration for paperclipai/paperclip. It was prepared from a read-only dashboard inventory on 2026-10-13. No dashboard settings or custom context were changed.

config.json records the observed review settings supported by Greptile's documented file schema.
files.json loads repository context and scopes architectural rule files.
rules.md explains how to apply the canonical Markdown rules in rules/.

Settings migrated to Git

Dashboard setting	Repository configuration
Automatic reviews on all events	`autoReview: ["open", "push", "rebase"]`
Exclude `dependabot[bot]`; remaining reviews use Base	`excludeAuthors`, `effort: "base"`
High strictness (dashboard says it does not comment on P2s)	`strictness: 3`
Do not replace the PR description	`shouldUpdateDescription: false`
Include PR summary, confidence score, and findings; no sequence diagram	The four section settings in `config.json`
Summary is not collapsible; default-open option is off	`summarySection.collapsible` and `defaultOpen` are `false`
Include a prompt to fix findings	`fixWithAI: true`
Status checks and status comments enabled	`statusCheck` and `statusCommentsEnabled` are `true`
Auto-approval disabled; stored risk ceiling is Low	`autoApprove.enabled: false`, `riskCeiling: "low"`

The existing PR-description and 1,000-line growth guidance is in rules/pull-request-review.mdc. That file also preserves the active, repository-specific rule not to request UI screenshots. This resolves the contradiction with the older organization instruction asking for screenshots.

The active dashboard pattern **/[Aa][Gg][Ee][Nn][Tt][Ss].md reported two files: AGENTS.md and docs/api/agents.md. Both are explicit references in files.json; the latter remains API context, not contributor policy. Future context files need explicit manifest entries. The inactive Contribution guidelines context remains inactive; it is not added as a separate context file. Rules scoped to other repositories are not copied here.

Settings still managed in Greptile

The following observed controls do not have equivalents in the published .greptile/ schema used for this migration. They remain dashboard settings:

Review draft pull requests: enabled.
Required confidence to pass the status check: 5/5.
Image badges: enabled.
Comment header: empty.
Default coding-agent badges: no agents shown.

Repository enablement, provider authentication, billing, integrations, and learned memory also remain service settings. Auto-approval risk instructions, if used later, are explicitly dashboard-only in Greptile's reference. Do not invent config keys for unsupported controls.

Cutover and maintenance

Greptile reads committed configuration from the reviewed branch. No reindex is required. Local changes alone are not visible to the hosted reviewer.

File-based review settings override dashboard defaults, but dashboard rules and instructions are additive. The existing dashboard copies are still active. This is a staged migration, not a completed dashboard cleanup. After a hosted review verifies the configuration, an authorized maintainer can retire duplicate dashboard context scoped to this repository. Do not remove shared organization instructions while other repositories still depend on them.

Keep each policy's body in rules/; update the files.json scope together with the rule's MDC frontmatter. The chat-channel rule includes both the directory and its sibling service entry point. See rules/README.md for authoring steps.

References: configuration and precedence, supported fields and file references.