DottaandPaperclip
cd12432947
## Thinking Path > - Paperclip manages AI agents and keeps their results attached to tasks. > - Native tools return links to saved task documents. > - Completion feedback asks agents to include those links. > - The file-delivery validator treated every such relative link as a workspace path. > - A valid document and CSV result could therefore fail completion when it cited the supplied document link. > - This change derives document links from the same verified publication projection for guidance and validation. > - Requested files still need their own verified delivery evidence. ## Linked Issues or Issue Description **What happened?** The native document tool and completion feedback produce a link such as `/EX/issues/EX-1#document-output`. When a task also requests a downloadable CSV, citing that link causes completion to reject it as a workspace-only file. This occurs even when the document is published and the file has a valid current-run delivery receipt. **Expected behavior** Accept a server-derived document link only when it names the current company/task and a currently attached revision with a matching native publication receipt. Keep the separate requested-file requirement and all foreign, stale, missing, and workspace-file guards. **Steps to reproduce** 1. Save a task document through the native `write_document` tool. 2. Publish a CSV through `register_deliverable`. 3. Ask completion feedback for the final-response guidance. 4. Cite its returned document link alongside the file receipt in the next completion report. 5. The old validator rejects the valid document link as a workspace-only file. **Paperclip version or commit** Current source checkout. The regression exercises the real native document producer and completion validator. **Deployment mode** Local source verification on macOS arm64 with Node 24.22.1, pinned pnpm 9.15.4, locked dependencies, temporary PostgreSQL, and a controlled remote file-reader boundary. No live provider or hosted deployment is included. ## What Changed - Derive the canonical document href in the existing company/task/current-revision publication query. - Use that same verified href in completion guidance and reference validation. - Keep file registration and hash/size receipt requirements separate from document evidence. - Cover evidence, artifact, and criterion references; foreign companies/tasks; bogus keys; local paths; and lost current-revision publication proof. - Exercise actual native document writes and CSV registration, including attachment download query and fragment links. - Update the execution contract and the document feature/access maps. ## Verification - Red before the production edit: native completion generated a real saved-document link, then rejected the same link alongside a valid published file. The failure was the workspace-only-file guard. - Green: 210 tests across native completion feedback, explicit output validation, and the existing native file-handoff suite pass. These use real PostgreSQL and native tool receipts; the remote file reader is controlled. - A saved document link alone still fails the explicit CSV requirement. A document whose current revision lacks its publication receipt is rejected. Foreign task/company links, missing keys, malformed links, and workspace paths remain rejected. - Full workspace typecheck, server typecheck, and production build pass. - `node scripts/check-maps.mjs`, `node scripts/check-module-boundaries.mjs`, and `git diff --check` pass. Map checks establish structure only. - Full `pnpm test:run` is running separately. There is no full-suite verdict yet. CI and review are pending. - Hosted acceptance and any recovery of existing tasks remain separate steps. This PR does not change final-response recovery or scheduling. ## Risks - An overly broad URL exception could admit foreign or unpublished output. The validator accepts only exact hrefs from the authenticated publication projection. - Document evidence could hide a missing requested file. A separate regression keeps that delivery gate effective. - The shared projection adds current task/company joins. Existing document feedback and publication tests cover those consumers. ## Model Used OpenAI `gpt-6.1-sol` through Codex, with reasoning, code editing, shell execution, and automated tests. The context-window size is not exposed in this session. ## 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 - [ ] 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>
9.1 KiB
navigation
| navigation | ||||||
|---|---|---|---|---|---|---|
|
Documents, attachments, and work products
People read and revise task documents, annotate specific content, open attached files, and inspect the outputs an agent hands back. The artifact library provides another route to the same work.
Feature ID: documents-artifacts.
Implementation: task documents, artifact library, document panel.
Agent access: companion.
Sub-features
documents:documents-artifacts/documents— edit versioned task documents and inspect or restore revisions.annotations:documents-artifacts/annotations— attach feedback to document content and inspect resolution state.attachments:documents-artifacts/attachments— upload, preview, and download allowed files with company access checks.work-products:documents-artifacts/work-products— link deliverables to their source task, resource, and review context.library:documents-artifacts/library— search, filter, group, and open artifact stacks.
How to get to it (user POV)
task-document
Open a document from the task thread or document side panel.
To create or edit a general task document, open Open a new tab → Artifacts in the task side panel, then New document or Document actions → Edit document. Edits use the shared versioned editor and autosave. Classic mode keeps that editor in the task body. Plans retain their conversation and approval flow and cannot be created through the general document editor. Unfinished new documents, including a body typed before its key, survive a tab switch or reload within the same account and task. Cancel removes the backup; a confirmed creation clears it.
Select an inline image to open the document's image gallery. Use the left and
right arrow keys or the Previous and Next buttons to move through images in
reading order. The URL retains the document and adds a one-based image position,
such as #document-report&image=2. Share or reload that URL to open the same image.
Revision and maximized-view parameters remain in the link. Escape, Close, or the
backdrop closes the gallery and returns focus to the image.
Coordinator decision receipts also open a pinned reviewed revision alongside the matching task interaction. Historical tabs retain their revision identity independently of the current document tab. Missing revisions are explicit and never silently replaced with the latest document. When a decision in one task reviews another task's document, the center pane keeps the originating conversation while the sidebar opens the document owner's exact revision. An inaccessible owner never falls back to the origin task's document.
task-output
Open an attachment, output card, or file link from a task. For direct uploads, use the task side panel's Open a new tab → Artifacts → Upload files or drop files anywhere in that panel. On mobile, open More actions → Properties first. Agent conversations do not expose this upload path.
artifact-library
Open /artifacts and its grouping, search, and media controls.
Driving it with Playwright and the Paperclip CLI
The explicit build-revise Product journey covers documents-artifacts/attachments: browser downloads of two ZIP versions, an independent content oracle, and preservation of the original. Its shared source is not proof of a pass on any deployed target.
The explicit task-document-persistence journey covers documents-artifacts/documents:
browser creation and editing, task reopen/reload, exact saved title/body and
independent original/latest revision reads, board-user authorship and zero agent
runs. The setup owns a backlog task but does not seed a document. Calibration
rejects stale content, lost history and foreign ownership. A target needs a fresh
live pass before adding this journey to its scheduled checks.
Preconditions: follow the baseline. Use a task with a text document, a small attachment, and a generated work product. Use nonsensitive fixture files.
task-document
Automated: documents service, annotations, and revision restore cover server contracts.
Document image galleries checks desktop, mobile, and Classic document views with real uploaded images and saved document revisions. It covers keyboard/button navigation, image URLs and reload, focus return, focus containment, scroll locking, dismissal, and revision links.
Exact revision panel checks pinned content and missing-revision behavior; this component test does not prove end-to-end conversation scrolling. Open a resolved receipt after making a new revision and verify the earlier body plus matching interaction in the browser.
Manual: Edit a paragraph, save, reload, and compare revisions. Add an annotation to a specific selection and inspect it after another edit. Resolve it through the supported action. Restore a disposable revision and confirm the new current document and history agree.
task-output
Automated: attachment routes and work products cover data/access behavior; artifact arrival browser suite targets arrival. Artifact uploads drives file selection/drop, filename collisions, retry, and preservation of paused/unassigned tasks.
Native completion feedback checks a real saved-document link alongside a verified CSV attachment, including attachment download query and fragment links. It rejects foreign task/company links, missing documents, unproven current revisions, and workspace files. The document alone cannot satisfy the requested file. These local tool/Postgres checks do not establish hosted delivery or browser rendering.
Manual: Upload a small Markdown file and CSV through Artifacts. Markdown becomes a versioned task document; other files become attachments. Read the document, download the CSV and compare bytes, then reload. Upload the same Markdown filename again and verify a separate suffixed document without overwriting the original. On a paused unassigned task, confirm upload does not start work or add comments. Verify agent-produced work products separately using an eligible test run. Test an inaccessible user/company and explicit missing workspace-only resources.
artifact-library
Automated: artifact page covers grouping, search requests, and pagination using mocks.
Manual: Find the task’s output through search and grouping, open its stack, page through results, and reload a direct stack link. Confirm the same file/content appears as from the task.
Gotchas
-
In Coordinator, saved plan cards use document chronology, so a plan written before its output appears first even when both writes share one native run. Authored issue-document links use the same compact sidebar-link surface and retain revision/annotation targets. Classic run embedding is unchanged. The UI does not remove or deduplicate canonical plan content.
-
A local path is not automatically an uploaded artifact accessible to another user.
-
A preview screenshot is not proof that download bytes or revision references are correct.
-
Version conflicts and stale annotations must stay visible rather than silently targeting different content.
Storybook verification
documents
Capability ID: documents-artifacts/documents.
Scope: ui Storybook: Writable/read-only document, save pending/failure/conflict, revision history/historical preview and restore confirmation. Production: Persist edited body and reload; append-only restore creates new revision; reject stale writes and inaccessible company/task. Sources: Source: IssueDocumentsSection.tsx, TaskDocumentPanel.tsx, documents.ts. Tests: IssueDocumentsSection.test.tsx, document-revisions.test.ts, documents-service.test.ts, issue-document-restore-routes.test.ts
Documentation scope: Artifacts and work products
Document/attachment/library/work-product journeys are mapped; every media preview type, storage backend, annotation conflict, and runtime-resource lifecycle variant remains separate.