---
id: SCR-PFM-SEC-031
title: HQ staff roles
route: /hq/staff/roles
surface: console
product_area: platform
module: security
revision: 1
status: draft
design_intent: proposed
implementation_evidence: observed
inference: []
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
purpose: Explain the three built-in HQ roles without offering custom-role editing.
supports:
- CAP-PFM-SEC-016
- CAP-PFM-SEC-013
permission: hq.roles.read
entry_from:
- /hq/staff
exits_to:
- /hq/staff
displays:
- field: Support Representative, Software Engineer and Rhythm Administrator definitions with permission keys
    grouped by area.
  source: listHqRoles
  provenance: observed
actions: []
states:
- loading
- error
- read-only
validation:
- BR-CAP-PFM-SEC-016-07
- BR-CAP-PFM-SEC-013-07
patterns:
- StaffOnly
- PageLayout
- PageHeader
- StaffTabs
- RoleCard
- Fallback Alert
component: components/console/hq/staff/hq-roles.tsx
evidence:
- 'react-console at baf6dae: components/console/hq/staff/hq-roles.tsx; the page route file; lib/security/api.ts,
  lib/hq/platform-ops.ts, lib/hq/platform.ts, lib/auth/*'
- react-console:lib/hq/use-hq-ops.ts:useHqRoles; lib/hq/permissions.ts:useHqPermissions; services-platform:modules/security/aws/api/hq-staff.routes.ts:listHqRoles
api_permission: hq.staff.read
examined_at: '2026-10-23'
examiner: codex
controls: [TC-AVL-001, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-005, TC-IAM-001, TC-IAM-002, TC-IAM-003, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-MON-002, TC-MON-003, TC-PI-001, TC-PI-003, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# HQ staff roles

## What the Screen Is For

Explain the three built-in HQ roles without offering custom-role editing.

## What It Shows and Lets People Do

The console gates this page with role-reading authority, while the role-list API requires staff-reading authority. If the read fails, the hook supplies locally known built-in definitions and the page warns that it is displaying fallback content.

## States and Errors

The page is read-only and offers no role-creation or edit operation. A displayed fallback definition is not evidence that the current backend catalog was read successfully.

The state rows describe observed loading, empty, refusal or inactive handling where present. Linked validation rules belong to the planning layer; client feedback and authoritative service checks have distinct responsibilities.

## Patterns It Must Respect

The pattern list names the built shared components and interaction patterns checked for this screen. This contract describes the existing screen; it supplies no replacement visual design.