Devin FoleyandPaperclip
5a6d0d08a7
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Recovery must preserve files and show the next operator action. > - A stopped run can leave a file repair hold after its recovery action is resolved. > - The task notice shows that hold but has no form to record verified file recovery. > - A chat connection can also replace the file repair instruction with a chat retry instruction. > - This pull request adds a file recovery form and preserves the file repair instruction. > - The form records evidence for the original run and keeps the current task status. ## Linked Issues or Issue Description **What happened?** A retained workspace file hold can block a task after its recovery action is resolved. The task page offers no file recovery form. A chat binding can hide the required file repair instruction. **Expected behavior** An authorized board member can record verified recovery of the original files. The server checks the original stop proof. The task keeps its current status and does not start another run. Chat instructions must not replace file repair instructions. **Steps to reproduce** 1. Create a stopped legacy run with a retained workspace recovery marker and a resolved recovery action. 2. Open its task page, including a task with a chat connection. 3. Observe that the file hold has no supported form to record verified recovery. Refs: #15857, #15824, #16095. Those PRs address shutdown export, native finalization and workspace source isolation. This PR uses the existing file repair API. ## What Changed - Add a board-only file recovery form with evidence and an explicit file verification confirmation. - Preserve the current task status when recording file recovery. - Project whether the original recovery marker supports file recording. - Keep file repair instructions when a task has a chat binding. - Add UI, route and Storybook examples for success, denial and chat-connected file holds. - Document the recovery flow and update the affected Storybook catalog entries. ## Verification - Merged master `c8efdbfba43` and resolved both rounds of catalog/index conflicts. Upstream review notes and classifications are preserved, together with all four retained-file recovery examples and their stable story IDs. Both fix branches also combine without merge conflicts or catalog fingerprint drift. - Passed locally after conflict resolution: 47 tests covering the file recovery UI, execution blocker notice and retained workspace repair route. The earlier ownership-route pass also covered 196 tests. - Passed: UI token gates, the complete Storybook catalog check with no drift errors, feature and agent map structure checks, and all 17 catalog/index script tests. Verification inventory counts match all 262 authored suites and 2,485 story IDs. The upstream production verification obligations remain intact. - Passed: full workspace typecheck, build and Storybook build on latest head `10ac22b35d0a4fe469cf620914845c509046da48`. The built index retains all four file-recovery story IDs. - Latest head `10ac22b35d0a4fe469cf620914845c509046da48` has 54 successful checks and two intentionally skipped Storybook checks. Apex is 5/5 on that exact commit, with no unresolved findings. The full general/serialized suites and all eight browser shards passed in CI. Local tests use the focused suites above. Storybook browser interactions have not been executed locally. - Manual check: open a task with a retained file hold. Verify that evidence and confirmation are required. Record verified file recovery. Confirm that its status stays unchanged and no run starts. Repeat without board runtime access and with an unverified stop receipt. ## Risks - The form records an operator attestation. It does not recover files itself or prove external action outcomes. - A stale source or missing stop proof must remain rejected by the existing server route. - No database migration or automatic task retry is added. ## Model Used OpenAI GPT-6 (`gpt-6`), used through Codex with reasoning, repository tools, code editing and test execution. The exact context window size is not exposed by this environment. ## 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 --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
Storybook map
The feature index connects the existing Storybook to stable capability
IDs from the upstream feature map. Story files remain
in ui/storybook/. The feature map and its maintenance skill do not depend on
this catalog. New capabilities or upstream recipe drift are reported to their
maintainer; this catalog does not redefine product behavior or permissions.
Ownership
- maintain-storybook owns story alignment, fixture corrections, classification, and this catalog.
- review-storybook consumes it to select and exercise examples, then reports evidence and drift.
- DESIGN.md governs design. Production verification remains with the existing product recipes and verification tools.
Catalog contract
catalog.json is the maintained inventory, with one entry per authored story file.
INDEX.md is generated from it, the upstream feature map, and the installed Storybook CSF parser. Titles,
export filtering, story counts and IDs come from source, not filename guesses.
All examples are retained, including historical suites. A file's first capability
is its primary home; remaining capabilities are lookup references, not copies.
Shared foundations may declare home: "foundations" to retain their folder and
sidebar while linking related capabilities. This override requires an exception
reason; it is not available for arbitrary feature homes.
Foundations/guides and proposals without a mapped capability need an exception
reason. An absent story is not automatically a feature gap.
Verification routes classifies the currently unassociated capabilities: UI examples to add, CLI/operator operations, and real browser checks. It records source review and existing test starting points, not executed proof. Update its rows/counts and source revision when associations or upstream capabilities change. A capability with a story still needs production verification for permissions, persistence, execution and provider behavior.
Folders and sidebar
Story files live in ui/storybook/stories/<primary-feature-area>/, using the first
capability's area slug. Related capabilities still point to the same story. Shared
fixture modules and assets live in ui/storybook/support/; production wrappers in
ui/storybook/prototypes/ retain their existing ownership.
The sidebar follows the section and feature names in the feature-map README, then
retains each suite's useful scenario grouping. Foundations contains shared component
examples with no primary product capability. Overview contains the catalog guide.
Every indexed feature has an Overview page, even when it has no cataloged examples.
The main guide and these pages use the same section, feature, and capability order
as the upstream map. Related suite links cross primary homes without copying stories.
Sidebar labels replace / with , because Storybook treats slashes as folders;
the index and page heading retain the original feature name.
Missing examples are explicit; historical examples and guides do not imply current
behavioral coverage.
ui/storybook/generated/ contains the derived index and one CSF Overview per
feature. The inline storySort.order in the preview config is also generated:
Storybook's indexer requires a literal there. Regenerate these outputs with the catalog command; do not edit
them or add them to the authored inventory. Their stable IDs use
feature-map-<area>--overview. Generated pages are explanatory guides and do not
increase example-suite counts. Storybook start/build checks this output for drift.
The generator fails on unexpected files rather than silently deleting them.
Each suite declares an explicit CSF id, recorded as stableId in the catalog.
The sidebarTitle can change without changing that identity. Existing story and
autodocs URLs and screenshot names remain valid. Do not derive a replacement ID
from a newly organized title. The checker rejects missing or changed explicit IDs,
incorrect feature folders, and sidebar titles outside their primary feature home.
Each entry records purpose, capability references, review sources/date/fingerprint, notes, and three independent dimensions:
| Dimension | Values |
|---|---|
| Product status | current: source comparison supports the named subject; proposed: intentional alternate design; historical: superseded reference retained for its original purpose; mixed: suite combines these; unreviewed: parity has not been established |
| Implementation | production: shipped subject with fixture/layout wrappers; prototype: locally implemented subject, even if it uses shared primitives; mixed: both subjects; guide: explanatory documentation |
| Data boundary | fixtures: props, callbacks, caches or API responses are simulated; fixture-server: requires a separately owned local API/database fixture with simulated upstream providers; static: explanatory/static examples |
current is a source-review classification, not a promise that every state renders
or that APIs, gates, persistence and providers passed live tests. unreviewed
entries still have an inventory/classification review; notes explain the deeper
parity work outstanding. Mixed files retain a note naming the important split.
Production components can legitimately use mock data. A prototype directory name
does not establish implementation: some wrappers there re-export shipped UI.
Review sources include the story, relevant local support and production subjects. Include directly rendered subjects regardless of import spelling, and primitives when the suite demonstrates them. Do not truncate the list to a fixed source count. Fingerprints make changes to those declared dependencies visible. They do not follow every transitive production import or infer semantic correctness. Shared preview/config/fixture changes have a separate fingerprint and require reviewing affected callers. Update fingerprints only after reviewing the change, and add missing dependencies when discovered. Date/revision context for the initial pass and executed evidence belong in REVIEW.md.
Maintenance commands
After installing workspace dependencies:
node scripts/storybook-catalog.mjs
node scripts/storybook-catalog.mjs --write
node --test scripts/storybook-catalog.test.mjs scripts/storybook-feature-index.test.mjs
The checker rejects unaccounted or deleted stories, invalid capability references,
duplicate entries/IDs, missing review sources, changed fingerprints and a stale
generated indexes and feature pages. --write only regenerates these outputs; it never refreshes review
fingerprints or blesses drift. Preserve IDs when changing titles or moving files;
compare the existing built Storybook index before and after such changes.
Feature outputs are regenerated before fingerprints are checked. If those writes
change a review source, the command fails with the affected review entries. Inspect
the generated change before updating those fingerprints and rerunning the command.
Use the existing Storybook workflow for builds,
browser review, and visual tests. Report source inspection, rendering, play
assertions, visual comparisons and production acceptance separately. Do not publish
new visual baselines just to make catalog maintenance pass.