# ADR 0004: Use Feishu Docs-like Permission Grants

## Status

Proposed.

## Context

Project collaboration needs more nuance than a hard-coded `owner / teacher / admin` model. Teachers may need to view a project, discuss it, trigger Claude, edit artifacts, manage members, or handle exceptional cancellation. These are related but not identical privileges.

Feishu cloud docs separates collaborators from operation settings:

- collaborators can be users, groups, departments, user groups, apps, or wiki members;
- collaborator roles are read, edit, or manage;
- settings separately control sharing outside the organization, copying/downloading, commenting, and collaborator management.

That split maps well to Curriculum Project Hub.

## Decision

Model project permissions as:

```text
PermissionGrant
- resource_type: project | artifact | project_group
- resource_id
- principal_type: user | feishu_chat | department | user_group | app
- principal_id
- role: read | edit | manage

PermissionSettings
- resource_type
- resource_id
- external_share_policy
- comment_policy
- copy_download_policy
- collaborator_management_policy
- agent_trigger_policy
- agent_cancel_policy
```

Use role-derived capabilities for ordinary actions, and settings for policy knobs:

- `read`: view project, artifacts, run history and project group metadata.
- `edit`: read plus discuss, comment, edit artifacts, trigger Claude runs and answer Claude choice cards.
- `manage`: edit plus manage collaborators, project settings, group binding and normal run cancellation policy.
- admin-only override: force release stuck locks and perform exceptional audit operations.

## Consequences

- We can grant access to a teacher, a whole Feishu project group, a department, or a custom user group using the same model.
- Claude invocation is explicit policy, not just "anyone in the group can run it" forever.
- "Who can cancel current processing" can be different from "who can force release a stuck lock".
- The model stays close to Feishu users' expectations without copying every Feishu-specific API detail.