Admin Spec: Org Chart Management

Field	Value
Area	Admin → Settings (admin-only settings page)
Status	Stub — created from the 2026-06-10 decision that Gospl masters the org chart. Awaiting sign-off.
Owner	TBD (Admin / People Team)
Contract	`/contracts/admin/org-chart.yaml`
Depends on	`_platform/identity-and-access.md` (owns the reporting-line graph + read queries); PR-01/PR-06
Access	Admin only (see PR-06). Sits inside the admin-only Settings page.

First spec in the Admin area. Admin houses settings/configuration pages that administer platform data. The org chart is mastered in Gospl (decided 2026-06-10), so it needs a maintenance UI — this is it. Seeding method: manual entry (no import).

1. Overview

An admin-only settings page to view and edit the organisation’s reporting structure. The reporting-line graph is read everywhere (manager visibility, scoped reports, Role Page); this page is the single place it is maintained. v1 is manual entry — assign and reassign each person’s manager, with the top of the tree having no manager.

2. Functional Requirements

FR-01 The page is reachable only by admin users (PR-06); others get no entry point and a 403 on the API.
FR-02 Display the current org chart — every user and who they report to (tree or searchable list).
FR-03 Set or change a user’s manager via manual selection from the user directory.
FR-04 Clear a user’s manager (mark them a top-level node, e.g. CEO).
FR-05 Reassigning a manager moves that user and their whole sub-tree with them (the chain stays intact).
FR-06 Cycle prevention — the system must reject any change that would make a user a manager of one of their own ancestors (no loops in the graph).
FR-07 Changes take effect immediately for all downstream access checks and reports (no caching that leaves visibility stale).
FR-08 Leavers — a removed/deactivated user’s direct reports must be reassignable so no one is orphaned. (Deactivation mechanism itself: see §C — directory concern.)

§A. Acceptance Criteria (stub)

Ref	Criterion
FR-01	A non-admin calling any org-chart write endpoint receives 403; the Settings entry point is hidden for them.
FR-03	Setting user A’s manager to B persists, and `GET /org/users/{B}/direct-reports` (platform) then includes A.
FR-05	Reassigning a mid-tree manager moves the whole sub-tree; `…/chain` for the new manager includes the moved sub-tree.
FR-06	A change that would create a cycle (A→B where B is already below A) is rejected with a clear error; the graph is unchanged.
FR-07	After a manager change, a manager-scoped read (e.g. Weekly Goals board for the moved user) reflects the new permission immediately.

§B. Data Model

No new core entity — this page writes the reportsTo edge owned by the platform org graph (_platform/identity-and-access.md §5). Tenant-scoped. Writes are admin-only; reads are the existing platform endpoints. An audit trail of changes (who reassigned whom, when) is recommended for an org-structure surface.

§C. Clarifications Needed

Initial seed — confirmed manual entry (2026-06-10). One-time question: is the starting set of users + a first-pass hierarchy entered by hand, or is the user list itself sourced elsewhere (directory) and only the edges entered here?
User provisioning / deactivation — creating and deactivating users is a directory concern (_platform/user-directory.md, planned), not org-chart. This spec assumes users already exist and only manages reporting edges. Confirm where user lifecycle lives.
Admin vs People Team — is org-chart editing admin-only, or also people_team? Spec assumes admin-only per your note; confirm.
Multiple top-level nodes — is more than one manager-less user allowed (e.g. multiple divisions), or exactly one root?

Out of Scope (v1)

Import/sync from any external system (manual entry only); automatic org-structure inference; user creation/deactivation (directory concern).