Document Markitect integration flow

docs/markitect-integration-flow.md

@@ -0,0 +1,119 @@
+# Markitect Integration Flow
+
+This document describes how Markitect should use flex-auth as its first
+protected-system consumer integration.
+
+## 1. Publish Resources
+
+Markitect emits a `FlexAuthResourceManifest` for each knowledge base or
+resource slice it wants flex-auth to authorize. The emitted manifest should use
+the namespace in `docs/markitect-resource-namespace.md` and include:
+
+- stable resource ids such as `document:internal-note`
+- resource type and parent links
+- path, labels, trust zone, owner, and durable backend metadata
+- `metadata.flex_auth_contract: resource-registration-v0`
+- `caring_profile: caring-0.4.0-rc2` when the emitter can provide it
+
+flex-auth imports the manifest through `internal/markitect.ImportResourceManifest`.
+The importer enriches resources with CARING scope and plane classification and
+returns diagnostics when a resource type, trust zone, label set, or CARING
+profile is missing or ambiguous.
+
+## 2. Submit Check Requests
+
+For one resource, Markitect submits `CheckRequest`:
+
+```text
+subject + action + resource + context + optional caring_context
+```
+
+For repeated checks, Markitect submits `BatchCheckRequest` with the same
+subject/action/context and a resource list. Resource order is preserved in the
+response.
+
+Markitect should pass local frontmatter and backend metadata as resource
+attributes when they affect policy:
+
+- `labels`
+- `trust_zone`
+- `markitect_path`
+- `frontmatter_visibility`
+- `source_revision`
+- `workflow_state`
+- `freshness_seconds`
+- `data_classes`
+
+Subject roles and groups should be normalized into subject attributes or loaded
+into the registry as subject/group/team manifests. CARING dimensions should be
+attached as `caring_context` when Markitect already knows the intended
+descriptor; otherwise flex-auth can derive descriptors from relationship facts.
+
+## 3. Enforce Decisions
+
+Markitect maps flex-auth decision envelopes into its gateway contract with
+`internal/markitect.ToGatewayDecision`.
+
+Expected effects:
+
+- `allow`: render, answer, package, activate, export, or run workflow.
+- `deny`: block the operation.
+- `redact`: continue with returned obligations such as `mask_fields`.
+- `audit_denied`: block or quarantine while preserving an audit-grade record.
+
+Markitect should enforce obligations before exposing data. For example, a
+`mask_fields` obligation must be applied before rendering or model use, and a
+`record_context_activation` obligation must be logged when a context package is
+activated.
+
+## 4. Record Decision IDs
+
+Every gateway operation should persist the flex-auth decision id alongside the
+Markitect request id, workflow id, rendered artifact id, or export id.
+
+At minimum, always record:
+
+- denies
+- redactions
+- exports
+- context package activations
+- workflow runs
+- support, break-glass, or other CARING exposure events
+
+The local flex-auth JSONL log is suitable for local development. Markitect may
+also write the same decision id into its own event log.
+
+## 5. Explain Decisions
+
+When users need an explanation, Markitect can call flex-auth `explain` or use
+the decision id to retrieve the persisted envelope and project it with
+`ToGatewayDecision`.
+
+Explanations should preserve CARING language:
+
+- subject relation and canonical role, for example `Customer Doer`
+- scope, for example `Resource document:internal-note`
+- plane, for example `Data`
+- capability, for example `View` or `Export`
+- exposure mode, for example `Masked`, `Plaintext`, or `Exportable`
+- restrictions, conditions, and conformance findings
+
+Example explanation:
+
+```text
+Customer Doer may View Data Plane resource document:internal-note because reader_group.
+```
+
+## Local Mapping Summary
+
+| Markitect local concept | flex-auth field | CARING dimension |
+| --- | --- | --- |
+| frontmatter visibility | `resource.attributes.frontmatter_visibility` | Exposure mode hint |
+| document labels | `resource.attributes.labels` | Scope and exposure hint |
+| owner/steward | `resource.owner`, subject groups/roles | Canonical role and relation |
+| workflow state | `resource.attributes.workflow_state`, request context | Lifecycle/condition hint |
+| context freshness | `request.context.freshness_seconds` | Condition and conformance finding |
+| export request | `action: export` | `Export` capability and `Exportable` exposure |
+
+The examples in `examples/markitect/` are the executable contract fixtures for
+this flow.

workplans/FLEX-WP-0003-markitect-consumer-integration.md

@@ -3,7 +3,7 @@ id: FLEX-WP-0003
 type: workplan
 title: "Markitect Consumer Integration"
 domain: netkingdom
-status: todo
+status: completed
 owner: flex-auth
 topic_slug: flex-auth
 planning_priority: P1
@@ -144,7 +144,7 @@ Add tests that produce flex-auth decisions in the shape Markitect expects:
 
 ```task
 id: FLEX-WP-0003-T006
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "e34b0303-4416-40a3-8b34-e0e80d644aea"
 ```