kandev/docs/plans/team-access/task-04-management-api.md

id, title, status, wave, depends_on, plan, spec

id	title	status	wave	depends_on	plan	spec
04-management-api	Management API, roles, and user directory	todo	2	03-reach-and-scope-resolution	plan.md	../../specs/workspaces/requirements/org-units.md

Task 04: Management API, Roles, and User Directory

Acceptance

• PATCH /api/v1/workspaces/{id} accepts visibility, gated on workspace.manage.
• POST /api/v1/workspaces/visibility/bulk sets visibility across the caller's own workspaces, for the one-time opt-in.
• PATCH /api/v1/orgs/current/settings accepts default_workspace_visibility, gated on org.settings.manage.
• GET/PUT/DELETE /api/v1/workspaces/{id}/members[/{userId}] list, add-or- re-role, and remove, gated on workspace.read / member.manage. PUT is idempotent and carries the workspace role.
• POST /api/v1/workspaces/{id}/transfer-ownership moves the accountable owner, demotes the previous owner to collaborator, and updates workspaces.owner_id in the same transaction. A target with no row is refused.
• Removing the last owner row, or the row matching owner_id, is refused with a distinct code.
• Setting visibility = 'org' on a workspace owned by a guest is refused.
• Adding a nonexistent, disabled, or already-present user returns 400 with a distinct code per case and writes nothing.
• PATCH /api/v1/users/{id} accepts the four org roles, gated on org.members.manage, with the last-owner and self-change guards.
• GET /api/v1/users/directory returns only id and display name for active users. A pinning test over the response field set fails if email, role, or status is ever added.
• Workspace DTOs carry visibility, member_count, viewer_role, and scopes; GET /api/v1/auth/me carries org_scopes.

Verification

• go test ./internal/task/... ./internal/user/... ./internal/auth/... -run 'TestVisibility|TestMember|TestTransferOwnership|TestUserDirectory|TestRoleChange'
• go test ./internal/user/... -run TestUserDirectoryFieldSet

Files Likely Touched

• apps/backend/internal/task/handlers/workspace_handlers.go
• apps/backend/internal/task/service/service_members.go
• apps/backend/internal/task/dto/dto.go
• apps/backend/internal/user/handlers/handlers.go, internal/user/dto/dto.go
• apps/backend/internal/auth/httpapi/handlers.go

Inputs

• Spec: API surface, Permissions, Failure modes; roles-and-scopes.md Permissions.
• Patterns: existing workspace handler shapes; the no-existence-leak rule for anything reachable cross-user.

Output Contract

Report the error-code matrix, the directory field pinning test and the mutation proving it fails, RED/GREEN commands, and set this task plus its plan checkbox to done.