Commit Graph
2 Commits
Author SHA1 Message Date
DottaandClaude Opus 5.5 fad8f051ca fix(ui): keep a saved task when its plan, run or work-product read answers 404 (#21684)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - #21671 saves the first chat frame of recently opened tasks in the
browser's read cache, so a hard load shows the chat before any response.
> - It also removes a task's saved data at once when a read of the task
or its chat is refused (401, 403 or 404).
> - A task without a plan answers 404 on `GET
/issues/:id/documents/plan`. That is a normal answer, but a reader that
does not catch it records a query error.
> - The cache treated that 404 as "the task is gone" and removed the
task and its saved chat. On staging, a task without a plan was therefore
never saved, so it never opened from the saved chat.
> - This pull request revokes on a 404 only for the task record and its
comments. 401 and 403 still revoke on every chat read.
> - The benefit is that tasks without a plan (most tasks) open from the
saved chat as intended.

## Linked Issues or Issue Description

**Describe the bug**
After #21671, a task without a plan is not kept in the saved read cache.
The first chat frame is not shown from the saved cache for that task.

**Steps to reproduce**
1. Open a task that has no plan document (for example PAP-4463 on
staging).
2. Look at the saved read cache (`paperclip:query-cache:v1:*` in local
storage) after the page settles.
3. The task's record and chat are missing. The page shows `GET
/api/issues/:id/documents/plan` answering 404.

**Expected behavior**
A 404 for a missing plan, active run or work products keeps the task.
Only a refusal of the task itself (its record or comments, or any
401/403) removes it.

**Actual behavior**
Any 404 on a saved chat read removes the task and its saved chat from
memory and storage.

Refs #21671.

## What Changed

- `ui/src/lib/persisted-query-cache.ts`: a chat read revokes the task on
401 or 403, or on 404 only for the recent comments. The task record
keeps revoking on 401, 403 and 404.
- `ui/src/lib/saved-task-chat.test.ts`: a 404 for a missing plan, active
run or work products keeps the task and its saved chat.
- `doc/ui-internals.md`: the read-cache rules state which 404s revoke.

## Verification

- `cd ui && npx vitest run src/lib/saved-task-chat.test.ts`: 24 passed.
With the change in `persisted-query-cache.ts` reverted, the 3 new cases
fail. The existing 401/403/404 revocation cases on recent comments still
pass.
- `src/lib/persisted-query-cache.test.ts` and
`src/lib/restored-task-chat-bootstrap.test.ts` pass (90 tests across the
three files). `pnpm --filter @paperclipai/ui typecheck` passes.
- Staging evidence (build `fc9e4cbbb`, PAP-4463): the only 4xx during
the load was `GET /api/issues/:id/documents/plan` 404, and the saved
record did not hold the task.

## Risks

- Low risk. A 404 on a plan, run or work-product read no longer revokes
the task. A task that was deleted or made unreadable still answers 404
or 403 on its record and comments, and that removes it. Any 401 or 403
still removes it.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`), Anthropic, used through Claude
Code with tool use (shell, file edits, browser automation).

## 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 <noreply@anthropic.com>
2026-11-14 18:43:18 -06:00
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