mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-13 15:55:46 +01:00
DottaandClaude
b5f62b3384
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - `rules/*.mdc` holds the architecture rules that reviewers and agents apply to a change > - Pull request #20585 added two rules: API route expectations and company-scope exceptions > - Review found that both rules state more than is true for the current code > - A rule that is too broad makes reviewers flag correct code and can make an agent add a wrong check > - This pull request corrects the scope of both rules and fixes one stale pointer > - The benefit is rules that match the code they describe ## Linked Issues or Issue Description Refs #20585 **Issue type** Incorrect contributor documentation. **Where is the issue?** `rules/api-route-expectations.mdc`, `rules/company-scope-exceptions.mdc`, `AGENTS.md` section 8, and `.agents/skills/honeycomb-tracing/SKILL.md`. **What's wrong?** - The API route rule said that every route checks company access. Instance-level routes such as `health.ts`, `liveness.ts`, `ready.ts`, `public-mcp.ts` and `org-chart-svg.ts` do not, and must not. - The API route rule told reviewers to flag each status code outside a list of seven. `429` and `503` are correct in some routes. - The company-scope rule said that it lists the only instance-wide data. `user_sidebar_preferences` is instance-wide and was not in the list. - The company-scope rule said that it applies to new files that its `globs` cannot match. - The `honeycomb-tracing` skill pointed to `AGENTS.md` for the Telemetry workflow. That text is now in `rules/data-paths.mdc`. **Suggested fix** Limit each rule to what is true, and repoint the skill. ## What Changed - The API route rule and `AGENTS.md` section 8 now apply to routes that read or write company data. - The API route rule names the instance-level routes and says not to add a company check to them. - The status code list is now a list of common codes. Reviewers flag an incorrect code, not an unlisted code. - The company-scope rule lists the sidebar company order as an instance-wide exception, in the text, the `globs`, and the Greptile scope. - The company-scope rule says "known data" and no longer claims to match new files. - The `honeycomb-tracing` skill points to `rules/data-paths.mdc`. ## Verification - Read the two rules and confirm that each named file exists. A local script checked the `globs` and the route names. - Confirm that `.greptile/files.json` is valid JSON and that its scope matches the rule `globs`. - No source code changed. No test suite ran locally. ## Risks - Low risk. The change is documentation only. - The list of instance-level routes can go out of date when a route is added. ## Model Used - Claude (Anthropic), in Claude Code with tool use. - `claude-fable-5-2`. ## 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 - [ ] 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 - [ ] 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 <noreply@anthropic.com>
45 lines
2.7 KiB
Plaintext
45 lines
2.7 KiB
Plaintext
---
|
|
description: The known instance-wide data is announcement dismissals, the announcement publication-ID registry, personal workspace presentation preferences, and the per-user sidebar company order; these grant no authority, and a new exception must be added to this list.
|
|
globs: "packages/db/src/schema/announcement_dismissals.ts,packages/shared/src/announcements.ts,server/src/routes/announcements.ts,server/src/services/announcements.ts,server/src/services/announcement-feed.ts,packages/db/src/schema/user_workspace_preferences.ts,packages/shared/src/workspace-preferences.ts,server/src/routes/workspace-preferences.ts,server/src/services/workspace-preferences.ts,packages/db/src/schema/user_sidebar_preferences.ts,packages/shared/src/types/sidebar-preferences.ts,server/src/routes/sidebar-preferences.ts,server/src/services/sidebar-preferences.ts"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# Company-scope exceptions
|
|
|
|
## Scope and purpose
|
|
|
|
Every domain entity is scoped to a company, and routes and services enforce
|
|
company boundaries. This rule lists the known data that is instance-wide and the
|
|
conditions that keep it safe. Its `globs` cover only the files of the listed
|
|
exceptions. `AGENTS.md` section 5 sends any change that adds data without a
|
|
company scope here.
|
|
|
|
## The exceptions
|
|
|
|
- **Announcement dismissals** are instance-wide user preferences, keyed by user
|
|
and announcement so they persist across companies. Their audit context must
|
|
still validate company membership.
|
|
- **The announcement publication-ID registry** is instance-level feed metadata.
|
|
It contains no company or user data.
|
|
- **Personal workspace presentation preferences** are instance-wide by user,
|
|
with validated company membership supplying audit context. They never grant
|
|
execution authority, change company capabilities or agent configuration, or
|
|
rewrite canonical work records. Optional conversation guidance must retain the
|
|
same action permissions.
|
|
- **The sidebar company order** in `user_sidebar_preferences` is instance-wide by
|
|
user, because it orders the user's companies. Sidebar preferences inside one
|
|
company stay company-scoped in `company_user_sidebar_preferences`.
|
|
|
|
## Requirements
|
|
|
|
- Do not add another instance-wide entity unless you add it to this list in the
|
|
same pull request and state why company scope does not fit.
|
|
- An instance-wide preference must not change what an actor is allowed to do.
|
|
|
|
## Review criteria
|
|
|
|
Flag a new table, route, or service that holds domain data without a company
|
|
scope and is not listed here. Flag an exception that skips company membership
|
|
validation for its audit context. Flag a preference that grants authority,
|
|
changes company or agent configuration, or rewrites work records.
|