feat: add BPMN inspection and workflow progress visuals

docs/BPMN_INTEROPERABILITY.md

@@ -0,0 +1,37 @@
+# BPMN Interoperability
+
+GovOPlaN distinguishes BPMN notation and XML interchange from executable
+workflow semantics.
+
+## Current Contract
+
+- `GET /api/v1/workflow/bpmn/profile` publishes the exact native support
+  profile.
+- `POST /api/v1/workflow/bpmn/inspect` safely parses bounded BPMN 2.0 XML,
+  inventories every BPMN model element, detects duplicate IDs and selected
+  dangling references, and classifies elements as interchange-only, natively
+  mappable, or natively executable.
+- XML entities, DTD-based expansion, oversized documents, and malformed roots
+  are rejected.
+- The native GovOPlaN graph remains the authoritative executable definition.
+
+Inspection is not XML Schema validation and does not claim that every BPMN
+semantic construct can be executed. A future `bpmn-js`/`bpmn-moddle` adapter
+can provide complete visual notation and XML round-tripping without forcing
+unsupported elements into the native runner.
+
+## Execution Boundary
+
+Adding a BPMN shape is not equivalent to implementing its token semantics,
+event subscriptions, compensation, transactions, choreography, or conformance
+behavior. Each executable mapping therefore needs:
+
+1. an explicit native semantic mapping;
+2. validation rules and lifecycle behavior;
+3. resumability and idempotency tests;
+4. migration and round-trip fixtures;
+5. a declared fallback when the installed runtime cannot execute it.
+
+Unsupported constructs remain visible and preserved by the future interchange
+adapter, but activation must remain blocked until an execution adapter declares
+support.