reserved-handle-policy

Reserved Handle Policy

Use this skill to protect a public handle namespace without turning a broad list into an unexplained permanent ban.

Start with the policy model

Separate two kinds of restriction:

1. hard_reserved: platform routes, authority terms, security identities, and service names that users must never claim.
2. manual_claim_required: scarce or impersonation-prone names that an administrator may assign after identity review.

Do not report both as merely taken. A caller needs to distinguish an existing account, a permanent platform reservation, and a claim that can be reviewed.

Read rationale.md before changing the tiers or source cohorts. Load reserved-handles.toml only when implementing, auditing, or inspecting the concrete list; it is intentionally kept out of the default context because it contains thousands of names.

Implementation workflow

1. Locate the canonical handle validator, signup command, rename command, availability endpoint, database uniqueness constraints, and administrator mutation boundary.
2. Preserve the product's existing normalization rules. Compare a normalized lowercase handle and a separator-stripped skeleton where separators are allowed.
3. Apply the stricter result in this order:
   • hard-reserved exact or confusable match;
   • an already-issued current or historical handle;
   • three-or-fewer-character skeleton;
   • manual-claim exact or confusable match;
   • otherwise available.
4. Reject protected names in open signup and self-service rename. Do not add a role-based bypass to those public commands.
5. If manual assignment is in scope, create a distinct administrator command with claimant evidence, reason, actor, timestamp, and audit record. A bootstrap-admin claim may be a narrowly documented exception.
6. Keep historical handles permanently unavailable if old profile or content URLs redirect through handle history.
7. Return an explicit machine-readable reason such as manual_claim_required and give the user honest UI copy.
8. Add focused tests for hard reservations, short handles, separators, one example from every cohort, existing/historical handles, bootstrap behavior, and audited assignment.