Files
PaperClipAI/doc/ISSUE-PRIVACY.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

240 lines
14 KiB
Markdown

# Private tasks and projects
Paperclip work is company-open by default. A task or project can instead be
marked private when its title, discussion, documents, attachments, work
products, or agent run traces should be limited to named participants.
## Who can read private work
A private task is readable by its responsible user, creating user, current
user or agent assignee, active task grantees, and members of its private
project. Restrictions flow down through children and run-created handoffs. Sharing or
assigning a task grants access to that task and its descendants; ancestors and
siblings require a separate grant. An assignment grant stays
active until it is explicitly revoked. Current assignment, ownership, private-project
membership, and inherited access remain independent reasons for access. The
sharing panel shows the source; revoking one grant does not remove other reasons.
Making a parent private protects existing descendants in the same transaction.
Moving a task under a private parent inherits privacy. A child cannot be made
public while it inherits a private boundary; making a parent public leaves its
existing private children private.
Private projects have a separate access-member list. A task-level grant can
expose one task without exposing its containing private project. Direct reads
by non-members return `404`, and list, count, search, attention, status-card,
activity, run-history, and tree-control surfaces apply the same predicate.
Visible blocker and mention edges may show a locked identifier-only stub; they
never include the private task's title or content.
Audit logs remain company-wide because they are the sanctioned oversight path.
They contain entity identifiers rather than private task content. Dashboard and
sidebar aggregate counts also remain company-wide: they may include private
work in totals, but do not expose titles, descriptions, or identifiers. The
issue list/count APIs themselves are viewer-filtered.
## Audited break-glass
Company owners and admins do not silently inherit private-task access. A normal
task detail request still returns `404`. When an owner or admin has a legitimate
emergency need, they must deliberately request the task with
`?breakGlass=true`.
Every successful break-glass read writes both:
- an `issue.break_glass_read` audit row containing the actor, task id, and time;
- a warning system notice on the private task so its owners can see that access occurred.
The flag does not change the canonical read predicate, create a grant, or make
future reads implicit. Non-admin members and agents cannot use it.
Cloud customer-success inspection is a separate operator capability. When an
operator enables it, the dedicated Cloud-signed permit can read private task
content within its company scope. Ordinary users, agent API keys, and plugins
cannot use that permit. Cloud enforces the inspection grant, expiration,
revocation, replay protection, and audit trail; this path does not create a task
grant or a task break-glass notice. Operators who require task ACLs on every
content read must leave `PAPERCLIP_CUSTOMER_SUCCESS_INSPECTION_ENABLED` disabled.
See [Cloud customer-success inspection support](CUSTOMER-SUCCESS-INSPECTION.md).
## Agent runs and shared-agent residual risk
Issue-bound run detail, events, transcripts, logs, and workspace operations use
the task ACL. Run authority is the intersection of the agent and the run's responsible user.
Reusing an agent does not transfer a different user's private-task permission.
Company run lists retain only timing/status/token/cost metadata for
non-members so budget oversight continues without exposing task identity or run
content.
Workspace operation records retain their original task and run sources even if
those entities are deleted or the operation is relinked. Deletion preserves the
audit record; unresolved sources make its details and log inaccessible. A
company-scoped run does not override a private task linked to the operation.
> **Residual risk — trusted agents (`trust-agent`).** Paperclip enforces privacy
> on reads from the control plane, but an agent that legitimately processes a
> private task may write learned content into shared persistent memory, its home
> directory, an external tool, or a later public response. V1 deliberately
> trusts the agent not to exfiltrate that context. Use isolated execution
> workspaces and appropriately trusted agents for sensitive work; task ACLs are
> not a sandbox or data-loss-prevention system.
## Plugins and notification/digest surfaces
Plugins (including any Slack notifier or digest plugin) are **non-member
principals**: they hold no company membership, task grant, or private-project
access. Rather than an allowlist of individually patched methods, the plugin
host centralizes the synthetic non-member check into shared helpers
(`requirePluginReadableIssue`, `pluginReadableIssueIdsByIds`,
`pluginRedactRelationSummary`) and routes **every** issue-derived read through
them. The complete inventory of issue-derived reads and their disposition:
- **Direct issue content** — `issues.list` (SQL predicate), `issues.get`,
`issues.listComments`, `issues.listAttachments`, `issues.getAttachmentContent`,
`issueDocuments.list`, `issueDocuments.get`: a private task is filtered from
list results, returns `null`/empty on soft reads, and reports "not found"
(indistinguishable from missing) on document reads.
- **Subtree / orchestration** — `issues.getSubtree` and
`issues.getOrchestrationSummary`: a private *root* reports "not found"; an
open root drops private descendants **before** any relation, document, run,
or assignee is fetched, so no private row or its metadata enters the payload.
- **Relationship metadata** — `issues.getRelations` (and the summaries echoed
by `issues.setBlockedBy` / `addBlockers` / `removeBlockers`, and the subtree
relation maps): blocker/blocks edges pointing at a private task are dropped,
recursing into nested terminal blockers, so its title, status, and assignee
never surface even on a public task.
- **Interactions** — `issues.listInteractions`: a private task yields no
interaction payloads.
A synthetic `{ type: "none" }` actor resolves to the same public-only scope as
any other non-member. This is why a digest broadcast to a shared channel —
whose audience is non-members by definition — cannot carry private issue
content. Writes that operate on a task must also satisfy its read predicate; plugin
capabilities do not substitute for task access. Returned relationship summaries
remain redacted.
There is intentionally **no plugin oversight exception**: unlike the
company-wide audit log, no plugin read path bypasses the predicate. A plugin
that must surface private work would need an explicit, separately designed
oversight capability; none exists today.
> **Residual metadata disclosure.** A plugin still learns aggregate,
> content-free signals about private work that mirror the accepted
> dashboard/count disclosure: `issues.getOrchestrationSummary` returns
> company-wide `openBudgetIncidents`. Its `costs`/token roll-up is limited to
> the readable subtree, and unreadable relationship edges are omitted entirely.
> No private title, body, comment, attachment, identifier, relationship target,
> or locked-edge signal is exposed.
## Rollout modes
`PAPERCLIP_ISSUE_PRIVACY_MODE=enforce` is the default. `shadow` records
structured would-deny decisions without enforcing them and exists only for
rollout diagnosis. `off` disables the task predicate. Operators should not use
`shadow` or `off` when private-task confidentiality is required.
The production gate includes positive and negative checks: an authorized reader
can read a shared child and its descendants, an unrelated reader cannot, and a
warm HTTP or live subscription loses that grant after revocation. Privacy grants
are read from the database without a cross-request positive cache.
## Migration and current runtime integration
Migration `0313_private_task_access.sql` adds the task/project ACL tables and
backfills privacy parent edges with indexed keyset batches. Run binding is derived
from native task identity, explicit issue identity, or legacy `issueId`/`taskId` context. Missing
source tasks remain issue-scoped tombstones. Context changes cannot turn those
runs into company-wide history. The migration is idempotent for preview installs;
existing explicit grants are preserved. Operators upgrading an unreleased preview
should inspect root grants created under its former whole-tree sharing semantics.
Migration `0314_private_task_draft_assets.sql` accompanies enforcement and binds
historical inline images to their first owned task. Unbound drafts remain
uploader-only under the new asset-content guard.
Both privacy migrations use the Paperclip migration executor's explicit
nontransactional path. Indexes on existing tables build concurrently; invalid builds are repaired on
retry. DDL statements commit individually and each 1,000-row
keyset batch commits before advancing, releasing schema and row locks. The
migration journal is written only after all batches succeed; an interruption
leaves the migration pending and its idempotent statements can be replayed.
Bootstrap uses the same executor, and other migrations retain a transaction per
file. Apply these migrations with `pnpm db:migrate`, before enabling the new
server or private-task UI.
Private output uses the same predicate on native tool searches and task context,
linked approvals, training exports, execution workspace APIs, stored run-response
assets, and WebSocket delivery. Workspace access requires permission for every
linked task. Chat publications recheck recipient identity and task access at the
provider boundary: private output is withheld from shared channels and from DMs
whose known recipients no longer qualify. This does not revoke Gmail or other
connection credentials; connection permissions continue to apply independently.
## CI leak-test inventory
The privacy regression gate is part of the normal server Vitest suite. Its
surface coverage is intentionally distributed beside the routes and services
it protects:
| Surface | Non-member regression coverage |
| --- | --- |
| Downward sharing, responsible-user intersection, mutation denial, provenance, live revocation | `privacy-production-review.test.ts` |
| Task detail, list, count, grants, documents, work products | `issue-access-grants-routes.test.ts`, `company-search-service.test.ts` |
| Search and machine extract | `company-search-service.test.ts`, `company-search-extract-service.test.ts` |
| Attention feed | `attention-service.test.ts` |
| Status-card hydrate and dry-run | `status-cards.test.ts` |
| Activity stream | `activity-service.test.ts`, `activity-routes.test.ts` |
| Run list, live run, detail, transcript, events, logs, operation history | `heartbeat-run-privacy-routes.test.ts` |
| Tree holds and tree control | `issue-tree-control-routes.test.ts` |
| Blocker and mention identifier-only stubs | `issue-access-grants-routes.test.ts` |
| Attachment content | `issue-attachment-routes.test.ts` |
| Private-project list and direct read | `projects-list-archived-routes.test.ts` |
| Plugin issue reads (list, get, comments, attachments, orchestration, subtree, relations, interactions, documents) | `plugin-orchestration-apis.test.ts` |
Adding a new task-derived read surface requires a non-member fixture in this
gate before the surface can ship.
Project privacy management belongs to its recorded creator (the responsible user
for agent-created projects), the personal-project owner, and administrators.
Project read membership alone never allows publishing the project or changing
its audience. Legacy projects recover ownership from their creation audit event;
when that evidence is missing, an administrator manages their privacy.
### Task privacy management hints
`GET /api/issues/:id/privacy-constraints` is available only to a principal who can read and manage that task. It returns the blocked scope kind and whether publishing leaves a personal project. It does not return protected parent or project names, identifiers, owners, or contents. This lets task owners manage their task without requiring access to its surrounding project. Visibility writes still enforce the canonical rules under the privacy-tree lock; these hints do not authorize a write.
## Rollout switch and run-history reads
`PAPERCLIP_ISSUE_PRIVACY_MODE` controls the canonical opt-in issue/project privacy predicate:
- `enforce` (default): return private issues only to implicit principals, issue grantees, or private-project access members; hide private projects from non-members
- `shadow`: log structured would-deny decisions but preserve existing reads; use only for rollout diagnosis
- `off`: skip the predicate and shadow logging
Grant checks read current database state; there is no positive privacy cache.
A run-history list is one read operation. It checks each distinct company,
run scope, and task binding once, then applies that decision to the related
rows in the same response. Every new list operation reads permissions again.
Sharing a task grants access to that task and its private descendants. Parents
and siblings need separate grants. An agent's access is intersected with its
run's responsible user's current access.
`enforce` is the production default. `shadow` and `off` disclose private data and
are only temporary diagnostic overrides. The old branch's historical sign-off
does not qualify the current runtime. See the sections above
for the model, validation coverage, break-glass behavior, and residual risks.
Issue-bound heartbeat runs inherit the same read predicate through the stored
`heartbeat_runs.scope_kind = 'issue'` and `issue_id` binding. Issue deletion
nulls the foreign key but preserves the explicit issue scope as a fail-closed
tombstone. Workspace-operation history is either deleted with its direct issue
or run binding, or remains bound to that fail-closed run tombstone, so it cannot
become company-level maintenance data through foreign-key nulling. In enforce mode, direct run detail, transcript,
event, log, and workspace-operation reads return `404` to non-members. Company
run-history and live-run lists retain a metadata-only row with timing, status,
token usage, and cost for budget oversight; issue identifiers, summaries, and
run content are omitted. Runs without an issue binding keep company-level
maintenance-run visibility.