@bluefly/openstandardagents 0.3.1 → 0.3.2

package/dist/spec/v0.3.1/ossa-0.3.1.schema.json

@@ -110,6 +110,237 @@
     }
   ],
   "definitions": {
+    "AgentIdentity": {
+      "type": "object",
+      "description": "Comprehensive agent identity configuration for service accounts, authentication, and observability",
+      "properties": {
+        "provider": {
+          "type": "string",
+          "enum": ["gitlab", "github", "azure-devops", "bitbucket", "generic"],
+          "description": "Identity provider type for service account integration"
+        },
+        "service_account": {
+          "type": "object",
+          "description": "Service account details for automated operations",
+          "required": ["username", "email"],
+          "properties": {
+            "id": {
+              "oneOf": [{"type": "integer"}, {"type": "string"}],
+              "description": "Provider-specific account ID"
+            },
+            "username": {
+              "type": "string",
+              "pattern": "^[a-z0-9_\\[\\]-]+$",
+              "minLength": 1,
+              "maxLength": 64,
+              "description": "Service account username"
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Service account email for git attribution"
+            },
+            "display_name": {
+              "type": "string",
+              "description": "Human-readable display name"
+            },
+            "roles": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["developer", "maintainer", "owner", "reporter", "guest"]
+              },
+              "description": "Roles assigned to this service account"
+            }
+          }
+        },
+        "authentication": {
+          "type": "object",
+          "description": "Authentication method configuration",
+          "properties": {
+            "method": {
+              "type": "string",
+              "enum": ["personal_access_token", "project_access_token", "group_access_token", "deploy_token", "oauth2", "ssh_key", "mtls", "github_app", "azure_service_principal"],
+              "default": "personal_access_token",
+              "description": "Authentication method type"
+            },
+            "scopes": {
+              "type": "array",
+              "items": {"type": "string"},
+              "description": "Required token scopes (provider-specific)"
+            },
+            "auto_refresh": {
+              "type": "boolean",
+              "default": false,
+              "description": "Automatically refresh token before expiry"
+            },
+            "expiry_warning_days": {
+              "type": "integer",
+              "default": 7,
+              "minimum": 1,
+              "maximum": 90,
+              "description": "Days before expiry to warn about token rotation"
+            },
+            "rotation_policy": {
+              "type": "object",
+              "properties": {
+                "enabled": {"type": "boolean", "default": false},
+                "interval_days": {"type": "integer", "default": 90, "minimum": 7, "maximum": 365},
+                "notify_on_rotation": {"type": "boolean", "default": true}
+              }
+            }
+          }
+        },
+        "token_source": {
+          "type": "object",
+          "description": "Token/credential source configuration with priority order",
+          "properties": {
+            "env_var": {
+              "type": "string",
+              "pattern": "^[A-Z][A-Z0-9_]*$",
+              "description": "Environment variable name containing the token (highest priority)"
+            },
+            "file_path": {
+              "type": "string",
+              "description": "Path to token file (second priority, supports ~ expansion)"
+            },
+            "vault": {
+              "type": "object",
+              "properties": {
+                "path": {"type": "string", "description": "Vault secret path"},
+                "key": {"type": "string", "default": "value"},
+                "role": {"type": "string", "description": "Vault role for authentication"}
+              }
+            },
+            "kubernetes_secret": {
+              "type": "object",
+              "properties": {
+                "name": {"type": "string"},
+                "namespace": {"type": "string"},
+                "key": {"type": "string", "default": "token"}
+              }
+            }
+          }
+        },
+        "patterns": {
+          "type": "array",
+          "items": {"type": "string"},
+          "description": "Glob patterns for auto-detection based on working directory (picomatch syntax)"
+        },
+        "fallback": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["provider", "service_account"],
+            "properties": {
+              "provider": {"type": "string", "enum": ["gitlab", "github", "azure-devops", "bitbucket", "generic"]},
+              "service_account": {"$ref": "#/definitions/AgentIdentity/properties/service_account"},
+              "token_source": {"$ref": "#/definitions/AgentIdentity/properties/token_source"},
+              "condition": {
+                "type": "object",
+                "properties": {
+                  "pattern_match": {"type": "array", "items": {"type": "string"}},
+                  "platform_unavailable": {"type": "boolean"}
+                }
+              }
+            }
+          },
+          "description": "Fallback identity chain for high availability"
+        },
+        "dora_tracking": {
+          "type": "object",
+          "description": "DORA metrics tracking configuration",
+          "properties": {
+            "enabled": {"type": "boolean", "default": false},
+            "metrics": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": ["deployment_frequency", "lead_time", "change_failure_rate", "mttr"]
+              },
+              "uniqueItems": true
+            },
+            "labels": {
+              "type": "object",
+              "additionalProperties": {"type": "string"},
+              "description": "Additional labels for metrics"
+            },
+            "prometheus": {
+              "type": "object",
+              "properties": {
+                "push_gateway": {"type": "string", "format": "uri"},
+                "job_name": {"type": "string"}
+              }
+            }
+          }
+        },
+        "session": {
+          "type": "object",
+          "description": "Session management for Claude Code integration",
+          "properties": {
+            "init_on_start": {"type": "boolean", "default": true},
+            "propagate_to_subprocesses": {"type": "boolean", "default": true},
+            "git_attribution": {"type": "boolean", "default": true},
+            "heartbeat_interval": {"type": "integer", "default": 300, "minimum": 30, "maximum": 3600},
+            "timeout": {"type": "integer", "default": 3600, "minimum": 60, "maximum": 86400},
+            "hooks": {
+              "type": "object",
+              "properties": {
+                "pre_prompt_submit": {"type": "boolean", "default": true},
+                "post_session": {"type": "boolean", "default": false}
+              }
+            }
+          }
+        },
+        "observability": {
+          "type": "object",
+          "description": "OpenTelemetry service identity for distributed tracing",
+          "properties": {
+            "service_name": {"type": "string"},
+            "service_namespace": {"type": "string"},
+            "service_version": {"type": "string", "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?$"},
+            "service_instance_id": {"type": "string"},
+            "resource_attributes": {
+              "type": "object",
+              "additionalProperties": {"type": "string"}
+            }
+          }
+        },
+        "security": {
+          "type": "object",
+          "description": "Security policies for identity management",
+          "properties": {
+            "token_encryption": {
+              "type": "string",
+              "enum": ["none", "at_rest", "in_transit", "both"],
+              "default": "both"
+            },
+            "minimum_token_length": {"type": "integer", "default": 32},
+            "prohibited_actions": {
+              "type": "array",
+              "items": {"type": "string"}
+            },
+            "required_approvals": {
+              "type": "object",
+              "properties": {
+                "force_push": {"type": "boolean", "default": true},
+                "delete_protected_branch": {"type": "boolean", "default": true},
+                "modify_ci_config": {"type": "boolean", "default": false}
+              }
+            },
+            "rate_limits": {
+              "type": "object",
+              "properties": {
+                "requests_per_minute": {"type": "integer", "default": 60},
+                "requests_per_hour": {"type": "integer", "default": 1000},
+                "git_operations_per_hour": {"type": "integer", "default": 100}
+              }
+            }
+          }
+        }
+      },
+      "additionalProperties": false
+    },
     "Metadata": {
       "type": "object",
       "required": [
@@ -523,27 +754,8 @@
           }
         },
         "identity": {
-          "type": "object",
-          "description": "OpenTelemetry service identity for tracing and observability",
-          "properties": {
-            "service_name": {
-              "type": "string",
-              "description": "Service name for OpenTelemetry traces"
-            },
-            "service_namespace": {
-              "type": "string",
-              "description": "Service namespace (e.g., production, staging, development)"
-            },
-            "service_version": {
-              "type": "string",
-              "description": "Service version (semver recommended)"
-            },
-            "service_instance_id": {
-              "type": "string",
-              "description": "Unique instance identifier"
-            }
-          },
-          "additionalProperties": false
+          "$ref": "#/definitions/AgentIdentity",
+          "description": "Agent identity configuration including service accounts, authentication, and observability (v0.3.1+)"
         },
         "compliance": {
           "type": "object",
@@ -959,6 +1171,10 @@
             },
             "additionalProperties": false
           }
+        },
+        "kubernetes": {
+          "$ref": "#/definitions/KubernetesConfig",
+          "description": "Kubernetes-specific configuration (KAS-inspired)"
         }
       },
       "additionalProperties": false
@@ -2801,6 +3017,69 @@
         }
       },
       "additionalProperties": false
+    },
+    "KubernetesConfig": {
+      "type": "object",
+      "description": "Kubernetes-specific runtime configuration (KAS-inspired)",
+      "properties": {
+        "namespace": {
+          "type": "string",
+          "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Kubernetes namespace (DNS-1123 subdomain)"
+        },
+        "service_account": {
+          "type": "string",
+          "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
+          "description": "Kubernetes service account name"
+        },
+        "api_server_url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Kubernetes API server URL (similar to KAS private API URL)"
+        },
+        "network_family": {
+          "type": "string",
+          "enum": [
+            "tcp",
+            "tcp4",
+            "tcp6"
+          ],
+          "default": "tcp",
+          "description": "Network family (KAS pattern: tcp, tcp4, tcp6)"
+        },
+        "health_check_endpoint": {
+          "type": "string",
+          "format": "uri",
+          "description": "Health check endpoint URL"
+        },
+        "config_map_ref": {
+          "type": "string",
+          "description": "Reference to Kubernetes ConfigMap"
+        },
+        "secret_ref": {
+          "type": "string",
+          "description": "Reference to Kubernetes Secret"
+        },
+        "rbac": {
+          "type": "object",
+          "properties": {
+            "role": {
+              "type": "string",
+              "description": "Kubernetes Role name"
+            },
+            "cluster_role": {
+              "type": "string",
+              "description": "Kubernetes ClusterRole name"
+            },
+            "role_binding": {
+              "type": "string",
+              "description": "Kubernetes RoleBinding name"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/dist/spec/v0.3.2/MIGRATION-v0.3.1-to-v0.3.2.md

@@ -0,0 +1,293 @@
+# Migration Guide: OSSA v0.3.1 → v0.3.2
+
+> **Status**: Draft  
+> **Last Updated**: 2025-12-28
+
+---
+
+## Overview
+
+OSSA v0.3.2 introduces **Access Tiers & Separation of Duties** while maintaining backward compatibility with v0.3.1 manifests.
+
+### Key Changes
+
+- ✅ **Backward Compatible**: v0.3.1 manifests validate against v0.3.2 schema
+- ✅ **Optional Features**: Access tiers are optional - existing agents work without changes
+- ✅ **Progressive Enhancement**: Add access tiers when ready
+
+---
+
+## Migration Path
+
+### Option 1: No Changes Required (Recommended for Existing Agents)
+
+**v0.3.1 agents continue to work without modification:**
+
+```yaml
+apiVersion: ossa/v0.3.1
+kind: Agent
+metadata:
+  name: my-agent
+spec:
+  role: You are a helpful assistant.
+  llm:
+    provider: anthropic
+    model: claude-sonnet
+```
+
+**This manifest validates against v0.3.2 schema** - no changes needed.
+
+### Option 2: Update API Version Only
+
+Simply update the `apiVersion` field:
+
+```yaml
+apiVersion: ossa/v0.3.2  # Changed from v0.3.1
+kind: Agent
+metadata:
+  name: my-agent
+spec:
+  role: You are a helpful assistant.
+  llm:
+    provider: anthropic
+    model: claude-sonnet
+```
+
+### Option 3: Add Access Tiers (Recommended for New Agents)
+
+Add access tier configuration for privilege separation:
+
+```yaml
+apiVersion: ossa/v0.3.2
+kind: Agent
+metadata:
+  name: my-agent
+  labels:
+    access_tier: tier_1_read  # Optional label
+spec:
+  type: analyzer  # Agent type
+  
+  # Access Tier Configuration (NEW in v0.3.2)
+  access:
+    tier: tier_1_read
+    permissions:
+      - read_code
+      - read_configs
+    prohibited:
+      - write_*
+    audit_level: standard
+  
+  # Separation of Duties (NEW in v0.3.2)
+  separation:
+    role: analyzer
+    conflicts_with:
+      - executor
+      - approver
+  
+  role: You are a helpful assistant.
+  llm:
+    provider: anthropic
+    model: claude-sonnet
+```
+
+---
+
+## Access Tier Selection Guide
+
+### Tier 1: Read Only (Analyzers)
+
+**Use for**: Scanners, reviewers, auditors, monitors
+
+```yaml
+access:
+  tier: tier_1_read
+  permissions:
+    - read_code
+    - read_configs
+    - read_logs
+    - execute_queries
+  prohibited:
+    - write_*
+    - delete_*
+    - execute_commands
+```
+
+**Examples**: Security scanners, code critics, compliance auditors
+
+### Tier 2: Write Limited (Workers)
+
+**Use for**: Doc generators, test writers, scaffolders
+
+```yaml
+access:
+  tier: tier_2_write_limited
+  permissions:
+    - read_*
+    - write_docs
+    - write_tests
+    - write_scaffolds
+    - create_issues
+    - create_mrs_draft
+  prohibited:
+    - write_production_code
+    - merge_mrs
+    - modify_infrastructure
+```
+
+**Examples**: Documentation generators, test generators, module scaffolders
+
+### Tier 3: Write Elevated (Operators)
+
+**Use for**: Deployers, infrastructure operators, incident responders
+
+```yaml
+access:
+  tier: tier_3_write_elevated
+  permissions:
+    - read_*
+    - write_*
+    - execute_deployments
+    - modify_pipelines
+    - merge_mrs  # With approval
+  prohibited:
+    - delete_production
+    - modify_secrets_direct
+    - bypass_approvals
+  requires_approval: true
+  approval_chain: standard
+```
+
+**Examples**: Deployment agents, CI/CD operators, infrastructure managers
+
+### Tier 4: Policy (Governors)
+
+**Use for**: Policy definers, compliance governors
+
+```yaml
+access:
+  tier: tier_4_policy
+  permissions:
+    - read_*
+    - define_policies
+    - publish_policies
+    - audit_compliance
+  prohibited:
+    - execute_*
+    - write_code
+    - modify_infrastructure
+  isolation: strict
+```
+
+**Examples**: Compliance policy engines, security policy managers
+
+---
+
+## Separation of Duties Rules
+
+### Critic-Executor Separation
+
+Agents that review **cannot** also execute:
+
+```yaml
+separation:
+  role: reviewer
+  conflicts_with:
+    - executor
+    - approver
+  prohibited_actions:
+    - execute
+    - merge
+    - approve
+```
+
+### Governor-Executor Separation
+
+Policy definers **cannot** execute:
+
+```yaml
+separation:
+  role: governor
+  conflicts_with:
+    - operator
+    - enforcer
+  prohibited_actions:
+    - execute
+    - remediate_direct
+```
+
+---
+
+## Validation
+
+### Validate v0.3.1 Manifest Against v0.3.2 Schema
+
+```bash
+# Using OSSA CLI
+ossa validate agent.ossa.yaml
+
+# Schema accepts both v0.3.1 and v0.3.2
+```
+
+### Validate Access Tier Configuration
+
+```bash
+# Check separation of duties
+ossa validate agent.ossa.yaml --check-separation
+
+# Audit tier violations
+ossa audit --tier-violations
+```
+
+---
+
+## Breaking Changes
+
+**None** - v0.3.2 is fully backward compatible with v0.3.1.
+
+### Deprecations
+
+None in v0.3.2.
+
+---
+
+## Examples
+
+See `spec/v0.3.2/examples/access-tiers/` for complete examples:
+
+- `security-scanner.ossa.yaml` - Tier 1 (Read Only)
+- `code-critic.ossa.yaml` - Tier 1 (Read Only)
+- `doc-generator.ossa.yaml` - Tier 2 (Write Limited)
+- `deployment-operator.ossa.yaml` - Tier 3 (Write Elevated)
+- `compliance-governor.ossa.yaml` - Tier 4 (Policy)
+
+---
+
+## FAQ
+
+### Do I need to migrate immediately?
+
+**No**. v0.3.1 manifests continue to work. Migrate when you need access tier features.
+
+### Can I mix v0.3.1 and v0.3.2 agents?
+
+**Yes**. Both versions validate against v0.3.2 schema.
+
+### What if I don't specify an access tier?
+
+**Agents work without access tiers**. They're optional for backward compatibility.
+
+### How do I choose the right tier?
+
+See [Access Tier Selection Guide](#access-tier-selection-guide) above.
+
+---
+
+## Related Documentation
+
+- [Access Tiers Specification](access_tiers.yaml)
+- [Schema Reference](ossa-0.3.2.schema.json)
+- [Examples](../examples/access-tiers/)
+
+---
+
+**Last Updated**: 2025-12-28