# Enterprise Guardrails Specification (EGS) — Generic Template

> **Version:** 1.1 | **Last Updated:** 2026-02-18  
> **Purpose:** Define the non-negotiable principles, constraints, and standards that every AI-DLC session must comply with. This specification acts as the "constitution" for all development activities: Mob Elaboration, Mob Construction, Code Elevation, and Operations.  
> **Audience:** Development teams, architects, product owners, facilitators.  
> **Usage:** Copy this template, fill in the bracketed sections with your organization's standards, and save as `aidlc-docs/egs_definition.md` in your project. Reference it from every AI-DLC prompt template.

---

## How This Document Works

Every AI-DLC session (Mob Elaboration, Mob Construction, Code Elevation) must reference this specification. The AI collaborator is instructed to:

1. Validate every artifact it generates against these guardrails before presenting to the team.
2. Flag any conflict between a proposed design/code and a guardrail, and propose a compliant alternative.
3. Include a "Guardrails Validation" step as the last checkbox in every phase/stage plan.
4. Generate a Guardrails Compliance Report as a Bolt completion artifact.

Guardrails are organized by category. Each guardrail has a severity level:

| Severity | Meaning |
|----------|---------|
| **Mandatory** | No exceptions. Violation blocks the Bolt. |
| **Required** | Exceptions require a documented ADR with risk acceptance signed by [approver role]. |
| **Recommended** | Best practice. Deviation should be noted but does not block. |

### Category Ownership

Each category should have a designated owner responsible for defining, reviewing, and updating its guardrails:

| Category | Suggested Owner |
|----------|----------------|
| 1. Security Baseline | [Security Lead / CISO] |
| 2. Compliance Constraints | [Compliance Officer / Legal] |
| 3. Architectural Guardrails | [Chief Architect / Architecture Board] |
| 4. Coding Standards | [Engineering Lead / Tech Lead] |
| 5. Operational Readiness | [Platform / SRE Lead] |
| 6. Cost Guardrails | [FinOps Lead / Engineering Manager] |
| 7. AI/GenAI Guardrails | [AI/ML Lead / Responsible AI Owner] |
| 8. Reliability Guardrails | [SRE Lead / Platform Lead] |
| 9. Performance Efficiency | [Engineering Lead / Architect] |
| 10. Sustainability | [Cloud Operations / Platform Lead] |

### Review Cadence

This specification must be reviewed **[quarterly / semi-annually]** by the category owners. Each review must confirm that guardrails remain relevant, severity levels are appropriate, and new organizational requirements are incorporated. Review outcomes must be recorded in the Revision History (§13).

---

## 1. Security Baseline

### 1.1 Encryption at Rest
| Guardrail | Severity |
|-----------|----------|
| All data at rest must be encrypted using [KMS / equivalent key management service] | Mandatory |
| [Specify key management strategy: AWS-managed keys, customer-managed CMKs, or both] | [Severity] |
| [Specify key rotation policy: automatic rotation every N days] | [Severity] |

### 1.2 Encryption in Transit
| Guardrail | Severity |
|-----------|----------|
| All data in transit must use TLS 1.2 or higher | Mandatory |
| [Specify certificate management approach: ACM, self-managed, etc.] | [Severity] |
| Internal service-to-service communication must also be encrypted | [Severity] |

### 1.3 Identity and Access Management
| Guardrail | Severity |
|-----------|----------|
| All IAM policies must follow the principle of least privilege | Mandatory |
| No wildcard (*) permissions in IAM policies for production accounts | Mandatory |
| No inline IAM policies; use managed policies attached to roles | Required |
| [Specify MFA requirements: all human users, privileged operations, etc.] | [Severity] |
| [Specify federation/SSO requirements] | [Severity] |
| Service-to-service authentication must use IAM roles, not long-lived credentials | Mandatory |

### 1.4 Secrets Management
| Guardrail | Severity |
|-----------|----------|
| No secrets, API keys, or credentials in source code | Mandatory |
| No secrets in environment variables for production workloads | Required |
| Secrets must be stored in [Secrets Manager / Parameter Store SecureString / equivalent] | Mandatory |
| [Specify secret rotation policy] | [Severity] |

### 1.5 Network Security
| Guardrail | Severity |
|-----------|----------|
| Compute resources must run in private subnets unless they require direct internet access | Required |
| [Specify VPC endpoint requirements for AWS service access] | [Severity] |
| [Specify security group rules: default deny, explicit allow] | [Severity] |
| [Specify WAF requirements for public-facing applications] | [Severity] |

### 1.6 Data Classification
| Guardrail | Severity |
|-----------|----------|
| All data must be classified before storage or processing: [define classification levels, e.g., Public, Internal, Confidential, Restricted] | Required |
| [Specify handling rules per classification level] | [Severity] |
| [Specify PII handling requirements: masking, tokenization, access controls] | [Severity] |

### 1.7 Threat Detection
| Guardrail | Severity |
|-----------|----------|
| [Specify threat detection services: GuardDuty, Security Hub, Config, third-party SIEM] | [Severity] |
| [Specify security standards/benchmarks to enable: CIS, AWS Foundational Security Best Practices] | [Severity] |
| [Specify triage SLA for critical/high findings] | [Severity] |

### 1.8 Incident Response
| Guardrail | Severity |
|-----------|----------|
| [Specify security incident response plan requirements] | [Severity] |
| [Specify incident classification and escalation procedures] | [Severity] |
| [Specify incident reporting timeline: e.g., within 1 hour of detection] | [Severity] |
| [Specify post-incident review requirements and feedback loop] | [Severity] |

### 1.9 Application Security
| Guardrail | Severity |
|-----------|----------|
| [Specify SAST requirements: tool, frequency (every build / nightly), severity thresholds that block merge] | [Severity] |
| [Specify DAST requirements: tool, frequency (per release / weekly on staging), scope] | [Severity] |
| [Specify penetration testing cadence: annually, before major releases, third-party vs. internal] | [Severity] |
| [Specify OWASP Top 10 compliance requirement for all web-facing applications] | [Severity] |
| [Specify vulnerability disclosure and remediation SLAs: critical within N days, high within N days] | [Severity] |

---

## 2. Compliance Constraints

### 2.1 Regulatory Frameworks
| Guardrail | Severity |
|-----------|----------|
| [List applicable frameworks: SOC2, ISO 27001, HIPAA, PCI-DSS, GDPR, local regulations] | [Severity per framework] |
| [Specify audit trail requirements: what events must be logged, retention period] | [Severity] |
| [Specify data residency restrictions: allowed regions, data sovereignty rules] | [Severity] |

### 2.2 Audit and Traceability
| Guardrail | Severity |
|-----------|----------|
| [Specify cloud trail / audit logging requirements] | [Severity] |
| Application-level audit logs must include: [timestamp, user/service identity, action, resource, outcome] | [Severity] |
| Audit logs must be immutable and retained for [N months/years] | [Severity] |

### 2.3 Data Retention and Disposal
| Guardrail | Severity |
|-----------|----------|
| [Specify retention policies per data classification level] | [Severity] |
| [Specify secure deletion procedures] | [Severity] |

---

## 3. Architectural Guardrails

### 3.1 Approved Patterns
| Guardrail | Severity |
|-----------|----------|
| [List approved architectural patterns, e.g., event-driven, CQRS, microservices, serverless-first] | Recommended |
| [List prohibited patterns, e.g., shared databases between services, synchronous chains >3 hops] | Required |
| [Specify API standards: REST with OpenAPI 3.x, GraphQL with schema-first, gRPC, etc.] | Required |
| [Specify API versioning strategy: URL path (/v1/), header (Accept-Version), query param; and deprecation policy] | [Severity] |

### 3.2 Service and Technology Constraints
| Guardrail | Severity |
|-----------|----------|
| [List approved cloud services / technology stack] | Recommended |
| [List prohibited or restricted services with rationale] | Required |
| [Specify regional availability requirements: services must be available in target deployment regions] | Required |

### 3.3 Service Boundaries
| Guardrail | Severity |
|-----------|----------|
| No direct database sharing between services; communicate via APIs or events | Required |
| Domain layer must have zero infrastructure dependencies (clean architecture) | Required |
| [Specify dependency direction rules] | [Severity] |

### 3.4 Multi-Account / Multi-Environment Strategy
| Guardrail | Severity |
|-----------|----------|
| [Specify account strategy: separate accounts for dev, staging, production] | [Severity] |
| [Specify environment promotion rules: what gates must pass before production] | [Severity] |

### 3.5 Event Schema Management
| Guardrail | Severity |
|-----------|----------|
| [Specify event schema registry requirements: EventBridge Schema Registry, Confluent, or equivalent] | [Severity] |
| [Specify schema evolution rules: backward-compatible changes only (additive fields); breaking changes require new event type] | [Severity] |
| [Specify dead letter queue (DLQ) requirements for failed event processing; DLQ alerts must be configured] | [Severity] |
| [Specify event contract testing requirements between producer and consumer services] | [Severity] |

---

## 4. Coding Standards

### 4.1 General Coding Principles
| Guardrail | Severity |
|-----------|----------|
| Code must be clean, simple, and explainable; prefer readability over cleverness | Required |
| [Specify language-specific conventions: linting rules, formatter configs, style guides] | Required |
| No hardcoded configuration values; externalize via [config service / environment-specific files] | Required |
| [Specify maximum function/method complexity thresholds] | Recommended |

### 4.2 Error Handling and Resilience
| Guardrail | Severity |
|-----------|----------|
| No silent exception catches; all exceptions must be logged with context | Required |
| [Specify structured error format: error codes, correlation IDs, user-safe messages] | Required |
| [Specify retry and circuit breaker requirements for external calls] | Recommended |

### 4.3 Logging Standards
| Guardrail | Severity |
|-----------|----------|
| All logs must be structured (JSON format) | Required |
| Mandatory log fields: [timestamp, correlation_id, level, service_name, message] | Required |
| No PII or secrets in log output | Mandatory |
| [Specify log levels usage: ERROR for failures, WARN for degraded, INFO for business events, DEBUG for troubleshooting] | Recommended |

### 4.4 Dependency Management
| Guardrail | Severity |
|-----------|----------|
| [Specify approved package registries] | Required |
| No pinning to "latest"; all dependencies must use explicit versions | Required |
| Prefer latest stable versions of all dependencies; avoid outdated packages with known fixes available | Required |
| [Specify vulnerability scanning requirements: SCA tools, severity thresholds that block builds] | Required |
| If an older version is required for compatibility, document the justification as a decision with an expiry date | Required |
| [Specify license restrictions: no GPL in proprietary code, etc.] | Required |

### 4.5 Test Coverage
| Guardrail | Severity |
|-----------|----------|
| [Specify minimum coverage per layer: domain logic ≥ N%, integration ≥ N%, e2e: critical paths] | Required |
| All acceptance criteria from user stories must have corresponding tests | Mandatory |
| [Specify test naming and organization conventions] | Recommended |

---

## 5. Operational Readiness

### 5.1 Observability
| Guardrail | Severity |
|-----------|----------|
| Every service must emit metrics, logs, and traces | Required |
| [Specify observability stack: CloudWatch, X-Ray, Prometheus, Grafana, etc.] | Required |
| [Specify mandatory metrics: latency, error rate, throughput, saturation] | Required |
| [Specify alerting requirements: what conditions trigger alerts, who gets notified] | Required |

### 5.2 Health Checks
| Guardrail | Severity |
|-----------|----------|
| Every deployed service must expose a health check endpoint | Required |
| Health checks must validate downstream dependencies (shallow and deep health) | Recommended |

### 5.3 Disaster Recovery
| Guardrail | Severity |
|-----------|----------|
| [Specify DR classification per workload tier: RTO/RPO targets] | Required |
| [Specify backup requirements: frequency, retention, cross-region replication] | Required |
| [Specify DR testing requirements: frequency, scope] | Recommended |

### 5.4 Deployment Standards
| Guardrail | Severity |
|-----------|----------|
| All deployments must be automated via CI/CD pipelines | Required |
| [Specify deployment strategy: blue-green, canary, rolling; no big-bang] | Required |
| [Specify rollback requirements: automated rollback on failure, maximum rollback time] | Required |
| [Specify IaC requirements: CloudFormation, CDK, Terraform] | Required |

### 5.5 Tagging Standards
| Guardrail | Severity |
|-----------|----------|
| [Specify mandatory resource tags: Environment, Service, Owner, CostCenter, etc.] | Required |
| [Specify tag enforcement mechanism: SCPs, Config rules, etc.] | Recommended |

### 5.6 Runbooks
| Guardrail | Severity |
|-----------|----------|
| Every deployed service must have an incident response runbook | Required |
| [Specify runbook minimum content: escalation path, common failure modes, recovery steps] | Required |

### 5.7 Continuous Improvement
| Guardrail | Severity |
|-----------|----------|
| [Specify post-incident review requirements: which severity levels, timeline, action tracking] | [Severity] |
| [Specify operational metrics to track: MTTR, MTTD, change failure rate, deployment frequency] | [Severity] |
| [Specify feedback loop: lessons learned must update runbooks, guardrails, and architecture decisions] | [Severity] |
| [Specify operational readiness review cadence per workload tier] | [Severity] |

---

## 6. Cost Guardrails

| Guardrail | Severity |
|-----------|----------|
| [Specify right-sizing expectations: no over-provisioned resources without ADR justification] | Required |
| [Specify budget alert thresholds per environment] | Recommended |
| [Specify approved instance families/sizes per workload type] | Recommended |
| [Specify reserved capacity / savings plan strategy] | Recommended |
| [Specify cost anomaly detection requirements] | Recommended |

---

## 7. AI/GenAI Guardrails

> Include this section only if the workload involves AI/ML components.

| Guardrail | Severity |
|-----------|----------|
| [Specify approved models and model providers] | Required |
| [Specify data handling for training/inference: no PII without anonymization] | Mandatory |
| [Specify prompt injection mitigation requirements] | Required |
| [Specify output validation requirements: hallucination detection, content filtering] | Required |
| [Specify human-in-the-loop requirements per risk level] | Required |
| [Specify model versioning and traceability requirements] | Required |
| [Specify bias evaluation and fairness testing requirements] | Recommended |

---

## 8. Reliability Guardrails

### 8.1 Availability Targets
| Guardrail | Severity |
|-----------|----------|
| Every production service must have a documented availability target (e.g., 99.9%, 99.95%, 99.99%) | Required |
| Availability targets must be aligned with business impact classification and SLA commitments | Required |
| [Specify tier definitions: Tier 1 = 99.99%, Tier 2 = 99.95%, Tier 3 = 99.9%, Tier 4 = best effort] | [Severity] |

### 8.2 Fault Tolerance
| Guardrail | Severity |
|-----------|----------|
| Production workloads must be deployed across multiple Availability Zones (minimum 2 AZs) | Required |
| [Specify multi-region requirements for critical workloads: active-active, active-passive, pilot light] | [Severity] |
| Stateless services must support horizontal scaling without session affinity | Required |
| Single points of failure must be identified and documented; each must have a mitigation plan or ADR exception | Required |

### 8.3 Graceful Degradation
| Guardrail | Severity |
|-----------|----------|
| Services must define degraded-mode behavior when non-critical dependencies are unavailable | Required |
| [Specify fallback strategies: cached responses, default values, feature flags, queue-and-retry] | [Severity] |
| Degraded mode must be observable: distinct metrics and alerts for degraded vs. healthy operation | Recommended |

### 8.4 Throttling and Rate Limiting
| Guardrail | Severity |
|-----------|----------|
| All public-facing APIs must implement rate limiting | Required |
| [Specify default rate limits per API tier: e.g., 1000 req/s standard, 100 req/s authenticated, custom for partners] | [Severity] |
| Rate limit responses must use standard HTTP 429 with Retry-After header | Required |
| Internal service-to-service calls must implement bulkhead patterns to prevent cascade failures | Recommended |

### 8.5 Failure Testing
| Guardrail | Severity |
|-----------|----------|
| [Specify failure testing requirements: chaos engineering, game days, fault injection frequency] | [Severity] |
| DR failover must be tested at least [annually / semi-annually] | Required |
| Automated recovery mechanisms must be validated in non-production environments before production deployment | Required |

### 8.6 Capacity Planning
| Guardrail | Severity |
|-----------|----------|
| [Specify capacity planning cadence: quarterly review of resource utilization vs. projected growth] | [Severity] |
| Auto-scaling policies must be configured for all variable-demand workloads | Required |
| Scaling limits (min/max) must be documented and reviewed against traffic projections | Recommended |

---

## 9. Performance Efficiency Guardrails

### 9.1 Performance Targets
| Guardrail | Severity |
|-----------|----------|
| Every user-facing service must have documented latency targets (p50, p95, p99) | Required |
| [Specify default targets: e.g., API p95 < 500ms, p99 < 1s; batch jobs complete within N hours] | [Severity] |
| Throughput targets must be defined for high-volume services | Required |

### 9.2 Resource Selection
| Guardrail | Severity |
|-----------|----------|
| Compute resources must be selected based on workload characteristics (CPU-bound, memory-bound, I/O-bound) | Required |
| [Specify preferred instance families: e.g., Graviton-based instances preferred for cost-performance ratio] | [Severity] |
| Database engine selection must be justified against workload access patterns (relational vs. NoSQL vs. in-memory) | Required |

### 9.3 Caching Strategy
| Guardrail | Severity |
|-----------|----------|
| Frequently accessed, infrequently changing data must use caching (ElastiCache, DAX, CloudFront, or application-level) | Recommended |
| [Specify cache invalidation strategy: TTL-based, event-driven, or hybrid] | [Severity] |
| Cache hit ratio must be monitored; ratio below [N%] triggers review | Recommended |

### 9.4 Auto-Scaling
| Guardrail | Severity |
|-----------|----------|
| All non-serverless compute must have auto-scaling policies configured | Required |
| Scaling policies must use target tracking (preferred) or step scaling; no manual scaling in production | Required |
| [Specify scaling metric preferences: CPU utilization, request count, queue depth, custom metrics] | [Severity] |
| Scale-in cooldown must be configured to prevent flapping | Recommended |

### 9.5 Load Testing
| Guardrail | Severity |
|-----------|----------|
| [Specify load testing requirements: before production launch, before major releases, periodic] | [Severity] |
| Load tests must validate performance targets under expected peak load (minimum 2x average) | Required |
| Load test results must be documented and compared against previous baselines | Recommended |

### 9.6 Data and Query Optimization
| Guardrail | Severity |
|-----------|----------|
| Database queries must be reviewed for efficiency: proper indexing, partition key design, query patterns | Required |
| [Specify N+1 query detection and prevention requirements] | [Severity] |
| Large dataset operations must use pagination; no unbounded queries | Required |

---

## 10. Sustainability Guardrails

> Aligned with the AWS Well-Architected Sustainability Pillar. Include this section to minimize the environmental impact of cloud workloads.

### 10.1 Region Selection
| Guardrail | Severity |
|-----------|----------|
| When multiple regions meet latency and compliance requirements, prefer regions with lower carbon intensity or proximity to renewable energy sources | Recommended |
| [Specify preferred regions for sustainability: e.g., us-west-2 (Oregon), eu-west-1 (Ireland)] | [Severity] |

### 10.2 Resource Efficiency
| Guardrail | Severity |
|-----------|----------|
| Prefer managed and serverless services that optimize resource utilization automatically | Recommended |
| [Specify Graviton / ARM-based instance preference for better performance-per-watt] | [Severity] |
| Idle resources must be identified and decommissioned or scheduled (dev/test auto-shutdown) | Recommended |

### 10.3 Alignment to Demand
| Guardrail | Severity |
|-----------|----------|
| Workloads must scale down during low-demand periods, not just scale up during peaks | Recommended |
| Non-production environments must have scheduled shutdown/startup policies | Recommended |
| [Specify batch job scheduling: prefer off-peak hours when grid carbon intensity is lower] | [Severity] |

### 10.4 Data Lifecycle
| Guardrail | Severity |
|-----------|----------|
| Storage classes must be tiered based on access frequency (S3 Intelligent-Tiering, Glacier for archives) | Recommended |
| Unused data must be identified and archived or deleted per retention policies | Recommended |
| [Specify data compression requirements for storage and transfer] | [Severity] |

### 10.5 Software Efficiency
| Guardrail | Severity |
|-----------|----------|
| Optimize code and algorithms to minimize compute cycles and memory usage | Recommended |
| [Specify efficient serialization formats: e.g., prefer binary (Protobuf, Avro) over JSON for high-volume internal communication] | [Severity] |
| Minimize unnecessary data transfer between services and regions | Recommended |

---

## 11. Guardrails Compliance Report Template

> Generate this report for every Bolt as part of the completion criteria.

```markdown
# Guardrails Compliance Report

| Field | Value |
|-------|-------|
| Unit | [Unit name] |
| Bolt | [Bolt number] |
| Date | [YYYY-MM-DD] |
| Validated by | [Name] |

## Compliance Summary

| Category | Total Guardrails | Compliant | Exceptions | Violations |
|----------|-----------------|-----------|------------|------------|
| Security Baseline | | | | |
| Compliance Constraints | | | | |
| Architectural Guardrails | | | | |
| Coding Standards | | | | |
| Operational Readiness | | | | |
| Cost Guardrails | | | | |
| AI/GenAI Guardrails | | | | |
| Reliability Guardrails | | | | |
| Performance Efficiency Guardrails | | | | |
| Sustainability Guardrails | | | | |

## Exceptions (with ADR reference)

| Guardrail | ADR Reference | Approved By | Expiry |
|-----------|---------------|-------------|--------|
| | | | |

## Violations (blockers)

| Guardrail | Description | Remediation Plan | Owner |
|-----------|-------------|------------------|-------|
| | | | |
```

---

## 12. Project-Specific Overrides

Project-specific exceptions to this specification must be documented in:

```
aidlc-docs/overrides/guardrails_overrides.md
```

Each override must include:
- The specific guardrail being overridden
- Justification (why the guardrail does not apply or cannot be met)
- Compensating controls (what alternative protection is in place)
- Approval (who approved the override and when)
- Expiry (when the override should be reviewed; maximum 6 months)

---

## 13. Revision History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 1.1 | 2026-02-18 | [Author] | Added Reliability Guardrails (§8), Performance Efficiency Guardrails (§9), Sustainability Guardrails (§10) for full AWS WAF pillar alignment. Added Application Security (§1.9), Event Schema Management (§3.5), API versioning (§3.1), Threat Detection (§1.7), Incident Response (§1.8), Continuous Improvement (§5.7). Added Category Ownership and Review Cadence to intro section. |
| 1.0 | [Date] | [Author] | Initial version |
