mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-13 15:38:22 +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>
51 lines
2.0 KiB
Plaintext
51 lines
2.0 KiB
Plaintext
---
|
|
description: Every API route that reads or writes company data checks company access and actor permissions, logs mutations to the activity log, and returns consistent HTTP errors.
|
|
globs: "server/src/routes/**"
|
|
alwaysApply: false
|
|
---
|
|
|
|
# API route expectations
|
|
|
|
## Scope and purpose
|
|
|
|
This rule applies to new or changed HTTP routes under `server/src/routes/`.
|
|
Paperclip is a multi-company control plane, so each route must keep one
|
|
company's data away from another company's actors.
|
|
|
|
## Auth model
|
|
|
|
- The base path is `/api`.
|
|
- Board access is treated as full-control operator context.
|
|
- Agent access uses bearer API keys (`agent_api_keys`), hashed at rest.
|
|
- Agent keys must not access other companies.
|
|
|
|
## Requirements
|
|
|
|
When you add or change an endpoint that reads or writes company data:
|
|
|
|
- Apply company access checks. Use the helpers in `server/src/routes/authz.ts`,
|
|
such as `assertCompanyAccess`, instead of a new check.
|
|
- Enforce actor permissions (board vs agent), for example with `assertBoard` or
|
|
`assertBoardOrAgent`.
|
|
- Write an activity log entry for each mutation.
|
|
- Return consistent HTTP errors. The common codes are
|
|
`400/401/403/404/409/422/500`. Other codes are valid when they are the correct
|
|
status, such as `429` for rate limits and `503` while the server starts or
|
|
drains.
|
|
|
|
Instance-level routes such as `health.ts`, `liveness.ts`, `ready.ts`,
|
|
`public-mcp.ts`, and `org-chart-svg.ts` have no company to check. Do not add a
|
|
company access check to a route that serves no company data.
|
|
|
|
The API reference for callers is in `docs/api/`. Update it when a public
|
|
endpoint changes.
|
|
|
|
## Review criteria
|
|
|
|
Flag a route that reads or writes company data without a company access check.
|
|
Flag a route that lets an agent key reach another company. Flag a mutation with
|
|
no activity log entry. Flag an error response with an incorrect status code or
|
|
an error that hides a failure behind a success status. Do not flag a correct
|
|
status code only because it is not in the common list. Do not flag an
|
|
instance-level route for a missing company check.
|