Refine workplans for CARING profile

docs/caring-architecture-blueprint.md

@@ -0,0 +1,203 @@
+# CARING Architecture Blueprint For Flex-Auth
+
+Date: 2026-05-17
+Status: Draft architecture blueprint
+Source standard: CARING 0.4.0-RC2 (`/home/worsch/helix-forge/wiki/CaringStandardRc2.md`)
+
+## Purpose
+
+This blueprint describes how flex-auth can serve as the practical,
+efficient reference implementation of the CARING standard while keeping
+the core authorization path small enough to build and operate.
+
+CARING remains the semantic standard. Flex-auth implements the subset
+needed to make CARING descriptors, policy conformance, decisions,
+explanations, and audit events executable.
+
+## Architecture Position
+
+CARING answers:
+
+```text
+What access semantics should a system expose, validate, explain, and audit?
+```
+
+Flex-auth answers:
+
+```text
+Given a subject, action, resource, context, policy package, and registry
+state, what decision should protected systems enforce?
+```
+
+The reference implementation relationship is:
+
+```text
+CARING standard
+  -> flex-auth CARING profile schemas
+  -> policy packages and conformance checks
+  -> check/batch/list/explain APIs
+  -> decision and exposure-event audit records
+```
+
+## Minimal CARING Profile
+
+The first implementation should pin a `caring_profile` version and define
+the following canonical fields in flex-auth API and schema artifacts:
+
+```text
+subject_type
+organization_relation
+canonical_role
+scope
+plane
+capabilities
+exposure_mode
+conditions
+lifecycle_state
+restrictions
+exposure_event
+derived_capabilities
+access_path
+```
+
+The core does not need to implement every CARING benchmark or native-system
+mapping immediately. It only needs the descriptor shape, enums, validation,
+and a place in decisions and audit records.
+
+## Core Data Types
+
+`pkg/api` should expose:
+
+```text
+CaringProfile
+CaringAccessDescriptor
+CaringConformanceFinding
+CaringExposureEvent
+CaringRestriction
+CaringDerivedCapability
+```
+
+These types should be referenced by:
+
+```text
+SubjectManifest
+ResourceManifest
+RelationshipFact
+PolicyPackageMetadata
+CheckRequest
+DecisionEnvelope
+AuditEvent
+```
+
+The `ResourceManifest` remains consumer-owned and lightweight. CARING
+classification should be optional on resources at first, with policy
+packages allowed to require specific fields for a protected system.
+
+## Decision Pipeline
+
+The efficient runtime path is:
+
+```text
+1. Normalize identity claims into a Subject.
+2. Load registry facts for resource, relationships, tenant, and groups.
+3. Build a CheckRequest with CARING context.
+4. Evaluate restrictions first.
+5. Evaluate scoped policy package rules.
+6. Produce a DecisionEnvelope.
+7. Attach CARING conformance findings and provenance.
+8. Persist audit/exposure-event records when required.
+```
+
+CARING conformance should not block the fast allow/deny path unless a
+policy marks a finding as enforcement-grade. Most early findings should
+be diagnostics, warnings, or audit requirements.
+
+## Conformance Model
+
+Flex-auth should support two CARING modes:
+
+```text
+descriptive
+  Map existing local roles, policy objects, and grants into CARING
+  descriptors. Report ambiguity, bundling, missing scope, missing plane,
+  induced access, and exposure gaps.
+
+prescriptive
+  Validate new policy packages and manifests against a CARING profile.
+  Fail on required fields, restriction precedence, tenant-boundary
+  violations, and explicit policy-plane or secret-plane violations.
+```
+
+The conformance output should use stable severities:
+
+```text
+info
+warning
+violation
+blocked
+```
+
+## Policy Package Shape
+
+Rego-in-Markdown policy packages should carry CARING frontmatter:
+
+```yaml
+caring:
+  profile: caring-0.4.0-rc2
+  canonical_roles: [Doer]
+  organization_relations: [Customer]
+  planes: [Data]
+  capabilities: [View]
+  exposure_modes: [Masked, Plaintext]
+  conditions: [PurposeBound, Logged]
+  restrictions: [ExportBlocked, CrossTenantBlocked]
+```
+
+The policy evaluator should provide this metadata to Rego and copy the
+matched CARING descriptor into the decision envelope.
+
+## Reference Implementation Boundaries
+
+Flex-auth should implement:
+
+```text
+CARING descriptor schemas
+CARING-aware policy package validation
+CARING-aware decision envelopes
+CARING explain output
+CARING exposure-event audit records
+CARING conformance fixtures
+```
+
+Flex-auth should not own:
+
+```text
+The CARING standard text
+The NetKingdom IAM Profile
+Identity-provider role issuance
+Consumer-specific product semantics
+Full benchmark mappings for every native access system
+```
+
+## Implementation Slices
+
+1. Pin the CARING profile and descriptors in `FLEX-WP-0002 P2.1`.
+2. Add registry fields and validation in `FLEX-WP-0002 P2.2`.
+3. Add policy frontmatter and diagnostics in `FLEX-WP-0002 P2.3`.
+4. Attach CARING metadata to `check` and `batch_check` in `FLEX-WP-0002 P2.4`.
+5. Use CARING language in `list_allowed` and `explain` in `FLEX-WP-0002 P2.5`.
+6. Persist CARING exposure events in `FLEX-WP-0002 P2.6`.
+7. Map Markitect fixtures as the first consumer benchmark in `FLEX-WP-0003`.
+8. Require delegated adapters in `FLEX-WP-0004` to preserve CARING envelope
+   fields even when backend-native semantics differ.
+
+## Open Design Choices
+
+The first implementation should decide:
+
+```text
+Whether CARING enum values are strict or extension-friendly.
+Whether conformance findings are always non-blocking by default.
+How much derived-capability analysis belongs in core versus adapters.
+How to version profile changes after CARING leaves RC status.
+```

docs/workplan-planning-map.md

@@ -1,6 +1,6 @@
 # Flex-Auth Workplan Planning Map
 
-Date: 2026-05-15
+Date: 2026-05-17
 
 ## Purpose
 
@@ -20,10 +20,10 @@ This document captures the current sequencing view for flex-auth workplans.
 | Workplan | Priority | Status | Depends On | Current View |
 | --- | --- | --- | --- | --- |
 | `FLEX-WP-0001` | complete | done | none | Repo intent, boundaries, and authorization landscape research are complete. |
-| `FLEX-WP-0005` | P0 | todo | `FLEX-WP-0001` | Foundations and Topaz alignment: ADR-001/002/003, Go skeleton, `FlexAuthResourceManifest` schema pin, Topaz mapping spike, IAM Profile citation, ops-warden boundary clarification. |
-| `FLEX-WP-0002` | P0 | blocked | `FLEX-WP-0001`, `FLEX-WP-0005` | Standalone policy-as-code core: schemas, local registry, Rego-in-Markdown policy packages, check APIs, explanations, decision log, CLI/service skeleton, tests. |
-| `FLEX-WP-0003` | P1 | blocked | `FLEX-WP-0002` | Markitect consumer integration: resource namespace, manifest import, action vocabulary, decision fixtures, integration docs. |
-| `FLEX-WP-0004` | P2 | blocked | `FLEX-WP-0002`, `FLEX-WP-0005` | Delegated PDP and directory adapters: Topaz adapter implementation (evaluation already done in `0005`), OpenFGA/SpiceDB, OPA/Cedar, Keycloak Authorization Services, Entra/Graph/SCIM. |
+| `FLEX-WP-0005` | complete | done | `FLEX-WP-0001` | Foundations and Topaz alignment are complete: ADR-001/002/003, Go skeleton, `FlexAuthResourceManifest` schema pin, Topaz mapping spike, IAM Profile citation, ops-warden boundary clarification. |
+| `FLEX-WP-0002` | P0 | ready | `FLEX-WP-0001`, `FLEX-WP-0005` | Standalone policy-as-code core: schemas, local registry, CARING profile/descriptors, Rego-in-Markdown policy packages, check APIs, explanations, decision log, CLI/service skeleton, tests. |
+| `FLEX-WP-0003` | P1 | blocked | `FLEX-WP-0002` | Markitect consumer integration and first CARING benchmark: resource namespace, manifest import, action vocabulary, descriptor fixtures, decision fixtures, integration docs. |
+| `FLEX-WP-0004` | P2 | blocked | `FLEX-WP-0002`, `FLEX-WP-0005` | Delegated PDP and directory adapters: Topaz adapter implementation (evaluation already done in `0005`), OpenFGA/SpiceDB, OPA/Cedar, Keycloak Authorization Services, Entra/Graph/SCIM, CARING envelope preservation. |
 
 ## Dependency Notes
 
@@ -33,18 +33,30 @@ It pulls forward the decisions the original `0002` left implicit (language,
 policy format, evaluator alignment) and runs the Topaz mapping spike
 before the core's schemas and check API are written.
 
+`docs/caring-architecture-blueprint.md` adds the 2026-05-17 CARING
+refinement: CARING remains the semantic standard, while flex-auth becomes
+the practical reference implementation for descriptors, conformance
+findings, decision metadata, explain output, and exposure-event audit
+records. This refinement changes the shape of `FLEX-WP-0002` but does not
+add a new predecessor workplan.
+
 `FLEX-WP-0002` comes after `0005` so the standalone evaluator embeds the
 OPA Rego library and produces decision envelopes shaped to match the
-delegated-mode envelopes added later.
+delegated-mode envelopes added later. It now also pins the executable
+CARING profile in the same schema slice.
 
 `FLEX-WP-0003` follows the core. Markitect has already completed its
 side of the contract in `MKTT-WP-0014`; flex-auth pins the manifest in
 `FLEX-WP-0005 T03` and implements the service-side registry and decision
 behavior in `0003`.
+It also becomes the first consumer benchmark for proving local roles and
+resource semantics can map cleanly into CARING dimensions.
 
 `FLEX-WP-0004` waits for the standalone core for the same reason as
 before, but its Topaz evaluation task moved to `0005 T04`; this workplan
 now implements the Topaz adapter against the spike's output.
+Delegated adapters must preserve flex-auth's CARING descriptor and
+conformance fields even when backend-native role semantics differ.
 
 ## State Hub Mirror