feat(calm): add deployment decorator standard to calm draft schema

calm-ai/tools/decorator-creation.md

@@ -157,17 +157,18 @@ Other deployment targets (e.g. AWS ECS, Azure Container Apps) follow the same pa
 
 ```json
 {
-    "$schema": "https://calm.finos.org/release/1.2/meta/decorators.json#/defs/decorator",
+    "$schema": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
     "unique-id": "aks-cluster-deployment-001",
     "type": "deployment",
     "target": ["aks-architecture.json"],
     "applies-to": ["aks-cluster"],
     "data": {
         "deployment-start-time": "2026-02-12T09:30:00Z",
+        "deployment-end-time": "2026-02-12T09:38:00Z",
         "deployment-status": "completed",
+        "deployment-environment": "production",
         "deployment-observability": "https://grafana.example.com/d/aks-prod/aks-cluster-overview",
-        "cluster": "prod-uksouth-aks-01",
-        "namespace": "trading-system"
+        "deployment-notes": "Routine upgrade to latest platform version"
     }
 }
 ```

calm/standards/README.md

@@ -0,0 +1,82 @@
+# FINOS Official CALM Standards
+
+This directory contains the official repository of standardized CALM decorator schemas and other reusable standards published and maintained by FINOS.
+
+## Purpose
+
+Standards in this directory represent validated, approved decorator schemas and cross-cutting architectural standards that organizations can use directly or extend for their specific needs. These standards enable consistent application of supplementary information across CALM architectures without modifying the core architecture definitions.
+
+## Organization
+
+Standards are organized by category to facilitate discovery and reuse:
+
+- **Deployment**: Deployment tracking decorators for various platforms (Kubernetes, AWS, Azure, etc.)
+- **Security**: Security context decorators including threat models, compliance frameworks, and security controls
+- **Business**: Business context decorators such as cost allocation, ownership, and organizational metadata
+- **Operational**: Operational decorators including runbooks, SLAs, incident contacts, and support information
+- **Observability**: Monitoring and observability decorators with dashboard links, alerting rules, and health checks
+- **Guide**: Architectural decision records (ADRs) and design guidance decorators
+
+## Standard Types
+
+Each standard definition includes:
+
+- **Schema definition**: JSON Schema extending the base decorator schema
+- **Required properties**: Mandatory fields for the decorator type
+- **Optional properties**: Additional fields for enhanced context
+- **Validation rules**: Constraints and patterns for data integrity
+- **Documentation**: Usage examples and implementation guidelines
+
+## Decorator Standards
+
+Decorator standards define typed schemas that extend the base decorator schema (`decorators.json#/defs/decorator`). Each decorator standard:
+
+1. Constrains the `type` field to a specific value
+2. Defines the structure of the `data` field
+3. Can be further extended by more specific schemas
+4. Maintains backward compatibility through versioning
+
+## Versioning
+
+All standards in this directory follow semantic versioning to ensure backward compatibility and clear evolution paths.
+
+## Publishing
+
+Standards in this directory are automatically published to the hosted CALM Hub when they are added, modified, or removed. This ensures that the latest approved standards are always available to the community.
+
+## Contributing
+
+To contribute new standards or modify existing ones:
+
+1. Follow the CALM decorator schema specification
+2. Ensure your standard extends the base decorator schema using `allOf`
+3. Provide clear documentation with comprehensive examples
+4. Include test cases demonstrating valid and invalid instances
+5. Submit a pull request with a detailed description of the standard's purpose and use cases
+
+## Usage
+
+Organizations can reference these standards directly in their decorator documents by using the appropriate `$schema` reference.
+
+```json
+{
+  "$schema": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
+  "unique-id": "my-deployment-001",
+  "type": "deployment",
+  "target": ["my-architecture.json"],
+  "applies-to": ["my-service"],
+  "data": {
+    "deployment-start-time": "2026-02-23T10:00:00Z",
+    "deployment-status": "completed"
+  }
+}
+```
+
+## Standard vs Other CALM Concepts
+
+| Concept | Purpose | Location |
+|---------|---------|----------|
+| **Standard** | Reusable decorator schemas and cross-cutting patterns | `calm/standards/` |
+| **Interface** | Communication protocol definitions | `calm/interfaces/` |
+| **Control** | Compliance and governance requirements | `calm/controls/` |
+| **Schema** | Core CALM meta-schemas | `calm/release/X.Y/meta/` |

calm/standards/deployment/README.md

@@ -0,0 +1,94 @@
+# Deployment Decorator Standards
+
+This directory contains standardized deployment decorator schemas for tracking deployment information across various platforms and environments.
+
+## Overview
+
+Deployment decorators attach deployment tracking information to architecture elements without modifying the core architecture definition. They enable tracking of deployment status, timing, observability links, and platform-specific details across the architecture lifecycle.
+
+## Base Deployment Decorator
+
+The base deployment decorator schema (`deployment.decorator.schema.json`) defines common deployment attributes applicable across all platforms:
+
+- **deployment-start-time**: ISO 8601 timestamp of when the deployment started (required)
+- **deployment-status**: Current deployment status (in-progress, completed, failed, rolled-back, pending) (required)
+- **deployment-end-time**: ISO 8601 timestamp of when the deployment completed or failed
+- **deployment-environment**: Target environment (e.g., production, staging, development)
+- **deployment-observability**: URI linking to logs, metrics, or observability dashboards
+- **deployment-notes**: Free-form notes or comments about the deployment
+
+## Platform-Specific Extensions
+
+Platform-specific deployment decorators extend the base deployment schema and add platform-specific attributes:
+
+- **Kubernetes**: Helm charts, clusters, namespaces
+- **AWS**: ECS services, CloudFormation stacks, regions
+- **Azure**: Resource groups, subscriptions, deployment slots
+- **Google Cloud**: Projects, regions, deployment managers
+
+## Usage
+
+### Basic Deployment Decorator
+
+```json
+{
+  "$schema": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
+  "unique-id": "api-service-deployment-001",
+  "type": "deployment",
+  "target": ["my-architecture.json"],
+  "applies-to": ["api-service"],
+  "data": {
+    "deployment-start-time": "2026-02-23T10:00:00Z",
+    "deployment-end-time": "2026-02-23T10:05:00Z",
+    "deployment-status": "completed",
+    "deployment-environment": "production",
+    "deployment-observability": "https://grafana.example.com/d/api-service",
+    "deployment-notes": "Successful deployment with zero downtime"
+  }
+}
+```
+
+### Kubernetes Deployment Decorator
+
+```json
+{
+  "$schema": "https://calm.finos.org/standards/deployment/kubernetes.decorator.schema.json",
+  "unique-id": "k8s-deployment-001",
+  "type": "deployment",
+  "target": ["my-architecture.json"],
+  "applies-to": ["api-service"],
+  "data": {
+    "deployment-start-time": "2026-02-23T10:00:00Z",
+    "deployment-end-time": "2026-02-23T10:08:00Z",
+    "deployment-status": "completed",
+    "deployment-environment": "production",
+    "deployment-observability": "https://grafana.example.com/d/k8s-prod",
+    "deployment-notes": "Rolling update with new features",
+    "kubernetes": {
+      "helm-chart": "my-api:1.2.3",
+      "cluster": "prod-us-west-01",
+      "namespace": "production"
+    }
+  }
+}
+```
+
+## Schema Inheritance
+
+```
+decorators.json (base decorator)
+  └── deployment.decorator.schema.json (deployment attributes)
+        ├── kubernetes.decorator.schema.json (Kubernetes-specific)
+        ├── aws-ecs.decorator.schema.json (AWS ECS-specific)
+        └── azure.decorator.schema.json (Azure-specific)
+```
+
+## Contributing
+
+To contribute new platform-specific deployment decorators:
+
+1. Extend `deployment.decorator.schema.json` using `allOf`
+2. Add platform-specific properties in a namespaced sub-object within `data`
+3. Set `additionalProperties: false` on your platform sub-object to lock down the schema
+4. Provide comprehensive examples and test cases
+5. Document all required and optional fields

calm/standards/deployment/deployment.decorator.schema.json

@@ -0,0 +1,68 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
+    "title": "CALM Deployment Decorator Schema",
+    "description": "Deployment decorator schema for tracking deployment information across various platforms and environments. Extends the base CALM decorator schema to add deployment-specific attributes.",
+    "allOf": [
+        {
+            "$ref": "https://calm.finos.org/release/1.2/meta/decorators.json#/defs/decorator"
+        },
+        {
+            "type": "object",
+            "properties": {
+                "type": {
+                    "const": "deployment",
+                    "description": "Must be 'deployment' for deployment decorators"
+                },
+                "data": {
+                    "type": "object",
+                    "properties": {
+                        "deployment-start-time": {
+                            "type": "string",
+                            "format": "date-time",
+                            "description": "ISO 8601 timestamp indicating when the deployment started"
+                        },
+                        "deployment-end-time": {
+                            "type": "string",
+                            "format": "date-time",
+                            "description": "ISO 8601 timestamp indicating when the deployment completed or failed"
+                        },
+                        "deployment-status": {
+                            "type": "string",
+                            "enum": [
+                                "pending",
+                                "in-progress",
+                                "completed",
+                                "failed",
+                                "rolled-back"
+                            ],
+                            "description": "Current status of the deployment"
+                        },
+                        "deployment-environment": {
+                            "type": "string",
+                            "description": "Target environment for the deployment (e.g., production, staging, development)"
+                        },
+                        "deployment-observability": {
+                            "type": "string",
+                            "format": "uri",
+                            "description": "URI linking to deployment logs, metrics, dashboards, or observability platform"
+                        },
+                        "deployment-notes": {
+                            "type": "string",
+                            "description": "Free-form notes or comments about the deployment"
+                        }
+                    },
+                    "required": [
+                        "deployment-start-time",
+                        "deployment-status"
+                    ],
+                    "additionalProperties": true
+                }
+            },
+            "required": [
+                "type",
+                "data"
+            ]
+        }
+    ]
+}

calm/standards/deployment/examples/README.md

@@ -0,0 +1,106 @@
+# Deployment Decorator Examples
+
+This directory contains example deployment decorator instances demonstrating various use cases and patterns.
+
+## Examples Overview
+
+| Example | Schema | Demonstrates |
+|---------|--------|-------------|
+| `simple-deployment.decorator.json` | Base deployment | Successful deployment with all optional fields |
+| `kubernetes-deployment.decorator.json` | Kubernetes-specific | Multi-service deployment with Kubernetes details |
+| `failed-deployment.decorator.json` | Base deployment | Failed deployment with rollback notes |
+| `multi-target-deployment.decorator.json` | Kubernetes-specific | Coordinated deployment across multiple architectures |
+
+## Usage Patterns
+
+### Single Service Deployment
+
+The simplest case - tracking a deployment for one service in one architecture:
+
+```json
+{
+  "target": ["my-architecture.json"],
+  "applies-to": ["my-service"]
+}
+```
+
+See: `simple-deployment.decorator.json`
+
+### Multi-Service Deployment
+
+Track a single deployment event that affects multiple services (e.g., coordinated release):
+
+```json
+{
+  "target": ["my-architecture.json"],
+  "applies-to": ["service-a", "service-b", "service-c"]
+}
+```
+
+See: `kubernetes-deployment.decorator.json`
+
+### Cross-Architecture Deployment
+
+Track a deployment that spans multiple architecture documents:
+
+```json
+{
+  "target": [
+    "frontend-architecture.json",
+    "backend-architecture.json"
+  ],
+  "applies-to": ["react-app", "api-gateway", "bff"]
+}
+```
+
+See: `multi-target-deployment.decorator.json`
+
+### Failed Deployment
+
+Document deployment failures with context for troubleshooting:
+
+```json
+{
+  "data": {
+    "deployment-status": "failed",
+    "deployment-notes": "Deployment failed due to..."
+  }
+}
+```
+
+See: `failed-deployment.decorator.json`
+
+## Platform-Specific Examples
+
+### Kubernetes
+
+Use the Kubernetes decorator schema when deploying to Kubernetes clusters:
+
+- Include Helm chart information
+- Specify cluster and namespace
+- Track workload type and replicas
+- Reference ConfigMaps and Secrets
+
+See: `kubernetes-deployment.decorator.json`
+
+## Best Practices
+
+1. **Unique IDs**: Use descriptive unique-id values that include the service name and deployment identifier
+2. **Timestamps**: Always use ISO 8601 format with timezone (preferably UTC)
+3. **Observability Links**: Link to deployment-specific dashboards or filtered log views
+4. **Notes**: Include context about what changed, why, and any issues encountered
+5. **Environment Clarity**: Always specify the target environment when relevant
+
+## Validation
+
+Validate decorator instances using the CALM CLI:
+
+```bash
+# Validate a deployment decorator
+calm validate --schema https://calm.finos.org/standards/deployment/deployment.decorator.schema.json \
+  simple-deployment.decorator.json
+
+# Validate a Kubernetes deployment decorator
+calm validate --schema https://calm.finos.org/standards/deployment/kubernetes.decorator.schema.json \
+  kubernetes-deployment.decorator.json
+```

calm/standards/deployment/examples/failed-deployment.decorator.json

@@ -0,0 +1,19 @@
+{
+    "$schema": "https://calm.finos.org/standards/deployment/deployment.decorator.schema.json",
+    "unique-id": "failed-deployment-example",
+    "type": "deployment",
+    "target": [
+        "example-architecture.json"
+    ],
+    "applies-to": [
+        "payment-processor"
+    ],
+    "data": {
+        "deployment-start-time": "2026-02-23T08:15:00Z",
+        "deployment-end-time": "2026-02-23T08:23:45Z",
+        "deployment-status": "failed",
+        "deployment-environment": "production",
+        "deployment-observability": "https://grafana.example.com/d/payment-processor-prod",
+        "deployment-notes": "Deployment failed due to database migration timeout. Rolling back to 2.9.1."
+    }
+}