more features checks. setup improvements

docs/features/checked/policy/policy-interop-framework.md

@@ -0,0 +1,68 @@
+# Policy Interop Framework (JSON Export/Import)
+
+## Module
+Policy
+
+## Status
+IMPLEMENTED
+
+## Description
+Policy interoperability framework enabling bidirectional JSON export/import of policy rules. OPA/Rego export was planned but only JSON export confirmed in source. Includes PolicyPack document format for portable policy bundles. Full interop library exists with JSON import/export, Rego code generation, and schema validation.
+
+## What's Implemented
+- **JsonPolicyExporter**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Export/JsonPolicyExporter.cs`
+  - `ExportToJsonAsync(PolicyPackDocument, PolicyExportRequest)`: canonical JSON export with deterministic output
+  - Environment filtering: merges environment-specific config into base config
+  - Remediation stripping option
+  - Content-addressed digest: `sha256:{hex}` via SHA256 of canonical JSON
+  - `ExportToRegoAsync()`: bridges to RegoCodeGenerator
+  - `SerializeCanonical()` / `SerializeToString()` static helpers
+- **JsonPolicyImporter**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/JsonPolicyImporter.cs`
+  - `ImportAsync(Stream, PolicyImportOptions)` / `ImportFromStringAsync()`
+  - Format detection via `FormatDetector` (auto-detect JSON vs Rego)
+  - API version validation: `policy.stellaops.io/v2` (with v1 compatibility adapter warning)
+  - Kind validation: `PolicyPack` or `PolicyOverride`
+  - Structural validation: duplicate gate IDs, duplicate rule names
+  - Remediation hint validation (code, actions)
+  - Diagnostic codes: FORMAT_UNKNOWN, REGO_USE_IMPORTER, JSON_PARSE_ERROR, VERSION_UNKNOWN, KIND_INVALID, GATE_ID_DUPLICATE, RULE_NAME_DUPLICATE
+  - `PolicyImportResult` with Success, Document, DetectedFormat, Diagnostics, GateCount, RuleCount
+- **RegoCodeGenerator**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Rego/RegoCodeGenerator.cs`
+  - Generates OPA Rego deny rules from PolicyPackDocument
+  - Gate type mappings: CvssThreshold, SignatureRequired, EvidenceFreshness, SbomPresence, MinimumConfidence, UnknownsBudget, ReachabilityRequirement
+  - Rego v1 syntax support (`import rego.v1`)
+  - Environment-specific config extraction
+  - Remediation hints as structured output rules
+  - Content-addressed digest of generated Rego source
+  - Warning collection for unmapped gate types
+- **RegoPolicyImporter**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/RegoPolicyImporter.cs`
+  - Imports Rego source back into PolicyPackDocument
+- **FormatDetector**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/FormatDetector.cs`
+  - Auto-detects policy format (JSON, Rego)
+- **PolicyPack v2 schema**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Schemas/policy-pack-v2.schema.json`
+- **Abstractions**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Abstractions/`
+  - `IPolicyExporter`, `IPolicyImporter`, `IRegoCodeGenerator` interfaces
+- **Contracts**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Contracts/`
+  - `PolicyPackDocument`, `PolicyExportRequest`, `PolicyImportOptions`, `RegoGenerationOptions`, `RegoExportResult`, `PolicyDiagnostic`
+- **DI registration**: `src/Policy/__Libraries/StellaOps.Policy.Interop/DependencyInjection/PolicyInteropServiceCollectionExtensions.cs`
+- **Evaluation**: `src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/`
+- **Tests**: `src/Policy/__Libraries/__Tests/StellaOps.Policy.Interop.Tests/`
+  - JsonPolicyExporterTests, JsonPolicyImporterTests, RegoPolicyImporterTests, RegoCodeGeneratorTests, FormatDetectorTests, PolicySchemaValidatorTests
+  - Golden file: `Fixtures/golden-policy-pack-v2.json`
+
+## What's Missing
+- **YAML import/export**: Only JSON and Rego formats are supported; no YAML PolicyPack format
+- **Policy diff/merge**: No tool to diff two PolicyPackDocuments and produce a delta or merge two packs
+- **CLI integration**: No `stella policy export --format rego` or `stella policy import` CLI commands wrapping the interop library
+- **Round-trip validation**: No automated tests proving JSON -> Rego -> JSON round-trip produces identical PolicyPackDocument
+- **OPA evaluation bridge**: Rego code is generated but there is no OPA evaluation service that runs the generated Rego against actual inputs
+
+## Implementation Plan
+- Add CLI commands wrapping export/import operations
+- Build round-trip test suite (JSON -> Rego -> JSON identity check)
+- Consider YAML format support using existing ScorePolicyLoader YAML infrastructure
+- Add policy diff/merge utility for comparing policy versions
+
+## Related Documentation
+- Interop library: `src/Policy/__Libraries/StellaOps.Policy.Interop/` (6 subdirectories)
+- Interop tests: `src/Policy/__Libraries/__Tests/StellaOps.Policy.Interop.Tests/`
+- Policy registry: `src/Policy/StellaOps.Policy.Registry/`