Add directory group resolver adapters

docs/directory-group-resolver-adapters.md

@@ -0,0 +1,65 @@
+# Directory Group Resolver Adapters
+
+Status: implemented for FLEX-WP-0004 P4.5.
+
+## Role
+
+Directory resolvers enrich flex-auth subjects with group and role
+evidence from external identity systems. They do not decide access by
+themselves. They feed the standalone, relationship, rule, Topaz, or
+Keycloak decision paths with fresh subject metadata and provenance.
+
+## Resolver Sources
+
+Implemented resolver boundaries:
+
+- Microsoft Graph group overage (`GraphResolver`)
+- SCIM provisioning (`SCIMResolver`)
+- LDAP/Active Directory (`LDAPResolver`)
+- Keycloak admin API (`KeycloakResolver`)
+
+Each resolver returns `ResolveResult` with normalized groups, roles,
+freshness, overage, and metadata.
+
+## Freshness
+
+Every result carries:
+
+- source
+- retrieval time
+- max age
+- expiry time
+- stale flag
+
+Decision adapters can use this metadata to deny stale directory evidence
+or to include freshness diagnostics in the decision envelope.
+
+## Overage
+
+Graph tokens can omit groups and instead emit overage indicators such
+as `_claim_names.groups` or `hasgroups=true`. The Graph resolver records
+that condition in `OverageMetadata` so downstream policy can distinguish
+"no groups" from "groups omitted, lookup required".
+
+## CARING Provenance
+
+Each `GroupGrant` and `RoleGrant` identifies:
+
+- source provider
+- originating claim name
+- organization relation
+- subject type
+- optional CARING descriptor
+
+This makes it possible to explain that a canonical role or group came
+from Graph, SCIM, LDAP/AD, or Keycloak rather than from an opaque token
+claim. The source remains inspectable in CARING conformance reviews.
+
+## Subject Enrichment
+
+`MergeResults` deduplicates groups and roles across providers while
+preserving freshness, overage, and descriptors. `ApplyToSubject` returns
+a subject with resolved groups/roles and directory metadata attached.
+
+The enriched subject can then flow through any flex-auth decision path
+without changing protected-system request or decision contracts.