gaia-framework 1.65.1 → 1.83.2

package/_gaia/lifecycle/templates/gap-entry-schema.md

@@ -0,0 +1,282 @@
+# Gap Entry Schema
+
+> **Version:** 1.2.0
+> **Story:** E11-S1, E12-S5, E11-S18
+> **Traces to:** FR-111, FR-123, US-38, ADR-021, ADR-022
+>
+> Standardized output schema for brownfield scan subagents (E11).
+> All scan agents MUST format gap entries using this schema.
+> Infra-specific categories added for infrastructure/platform project support (E12-S5).
+> Location: `_gaia/lifecycle/templates/gap-entry-schema.md`
+
+## Schema Definition
+
+Each gap entry is a YAML object with the following fields:
+
+```yaml
+id: "GAP-{scan_type}-{seq}"
+category: "<enum>"
+severity: "<enum>"
+title: "<string>"
+description: "<string>"
+evidence:
+  file: "<relative-path>"
+  line: <number-or-range>
+  protocol: "<string>"           # Optional
+recommendation: "<string>"
+verified_by: "<agent-id>"
+confidence: "<enum>"
+```
+
+## Field Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Unique identifier. Format: `GAP-{scan_type}-{seq}` where `scan_type` maps to the category and `seq` is a zero-padded 3-digit sequence (e.g., `GAP-dead-code-001`) |
+| `category` | enum | yes | Gap classification — must be one of the 12 allowed values (see Category Enum) |
+| `severity` | enum | yes | Impact level — must be one of the 5 allowed values (see Severity Enum) |
+| `title` | string | yes | Short summary of the gap (max 80 characters) |
+| `description` | string | yes | Detailed explanation of the gap, what it means, and why it matters |
+| `evidence` | object | yes | Source code evidence with required `file` and `line` sub-fields, plus optional `protocol` sub-field (see Evidence Object) |
+| `recommendation` | string | yes | Actionable fix or remediation guidance |
+| `verified_by` | string | yes | ID of the scan agent that produced this finding (e.g., `dead-code-analyzer`, `config-scanner`) |
+| `confidence` | enum | yes | Agent's confidence in the finding accuracy (see Confidence Enum) |
+
+## Enums
+
+### Severity Enum
+
+| Value | Description |
+|-------|-------------|
+| `critical` | Blocks deployment or causes data loss |
+| `high` | Significant risk requiring prompt attention |
+| `medium` | Moderate risk, should be addressed in current sprint |
+| `low` | Minor issue, can be deferred |
+| `info` | Informational finding, no immediate action needed |
+
+### Category Enum
+
+12 categories total — 7 application categories (E11-S1) plus 5 infrastructure categories (E12-S5):
+
+#### Application Categories (7)
+
+| Value | Scan Agent | Description |
+|-------|------------|-------------|
+| `config-contradiction` | E11-S2 | Configuration files contradict each other or runtime behavior |
+| `dead-code` | E11-S3 | Unreachable code, unused exports, orphaned files |
+| `hard-coded-logic` | E11-S4 | Magic numbers, embedded URLs, environment-specific constants |
+| `security-endpoint` | E11-S5 | Unprotected routes, missing auth, exposed secrets |
+| `runtime-behavior` | E11-S6 | Behavior that only manifests at runtime (race conditions, memory leaks) |
+| `doc-code-drift` | E11-S7 | Documentation does not match actual code behavior |
+| `integration-seam` | E11-S8 | Fragile integration points, tight coupling, missing contracts |
+
+#### Infrastructure Categories (5) — ADR-022 §10.16.5
+
+| Value | Infra PRD Section | Description |
+|-------|-------------------|-------------|
+| `resource-drift` | Resource Specifications | Declared infrastructure state differs from actual deployed state (e.g., Terraform state mismatch, orphaned cloud resources) |
+| `config-sprawl` | Environment Strategy & DX | Configuration values duplicated across multiple files without a single source of truth (e.g., same port in Dockerfile, Helm values, and Terraform variables) |
+| `secret-exposure` | Security Posture | Secrets, credentials, or sensitive values present in source files, environment configs, or IaC definitions without proper secrets management |
+| `missing-policy` | Verification Strategy | Infrastructure lacks policy-as-code enforcement (e.g., no OPA/Rego, no Checkov rules, no tfsec scans for security/compliance) |
+| `environment-skew` | Environment Strategy & DX | Environment definitions (dev/staging/prod) have inconsistent resource specifications, missing parity, or undocumented differences |
+
+### Confidence Enum
+
+| Value | Description |
+|-------|-------------|
+| `high` | Strong evidence, verified through multiple signals |
+| `medium` | Reasonable evidence, single signal source |
+| `low` | Weak evidence, needs human verification |
+
+## Evidence Object
+
+The `evidence` field is a composite object grouping source location data:
+
+```yaml
+evidence:
+  file: "src/services/auth.ts"    # Relative path from project root (non-empty string)
+  line: 42                        # Single line number
+  protocol: "rest"                # Optional. Protocol type
+```
+
+Or with a line range:
+
+```yaml
+evidence:
+  file: "config/database.yml"
+  line: "15-28"                   # Line range (start-end)
+```
+
+Or without the optional protocol field (backward compatible):
+
+```yaml
+evidence:
+  file: "src/utils/helper.ts"
+  line: 10
+```
+
+| Sub-field | Type | Required | Constraints |
+|-----------|------|----------|-------------|
+| `file` | string | yes | Relative path from project root. Must be non-empty. |
+| `line` | number or string | yes | Single line number (integer) or range as `"start-end"` string |
+| `protocol` | string | no | Optional. One of `rest`, `graphql`, `grpc`, `websocket`, or any custom string. Omit if not applicable. When present, must be a non-empty string. |
+
+## ID Format
+
+Pattern: `GAP-{scan_type}-{seq}`
+
+- `scan_type` is the category value (e.g., `dead-code`, `config-contradiction`)
+- `seq` is a zero-padded 3-digit sequence number starting at 001
+- Regex: `^GAP-(config-contradiction|dead-code|hard-coded-logic|security-endpoint|runtime-behavior|doc-code-drift|integration-seam|resource-drift|config-sprawl|secret-exposure|missing-policy|environment-skew)-\d{3}$`
+
+The `scan_type` component in the ID maps directly to the `category` value. See the Category Enum tables (Application + Infrastructure) for the full list of valid scan types.
+
+## Validation Rules
+
+All fields listed in the Field Reference are **required** — a gap entry with any missing field is invalid.
+
+### Enum Validation
+
+- `severity` must be exactly one of: `critical`, `high`, `medium`, `low`, `info`
+- `category` must be exactly one of: `config-contradiction`, `dead-code`, `hard-coded-logic`, `security-endpoint`, `runtime-behavior`, `doc-code-drift`, `integration-seam`, `resource-drift`, `config-sprawl`, `secret-exposure`, `missing-policy`, `environment-skew`
+- `confidence` must be exactly one of: `high`, `medium`, `low`
+- Any value not in the enum set must be rejected
+
+### Format Validation
+
+- `id` must match the regex `^GAP-(config-contradiction|dead-code|hard-coded-logic|security-endpoint|runtime-behavior|doc-code-drift|integration-seam|resource-drift|config-sprawl|secret-exposure|missing-policy|environment-skew)-\d{3}$`
+- `evidence.file` must be a non-empty string containing a relative path (no leading `/`)
+- `evidence.line` must be a positive integer or a range string matching `^\d+-\d+$`
+- `title` should not exceed 80 characters
+- `verified_by` must be a non-empty string identifying the scan agent
+- `evidence.protocol` when present, must be a non-empty string
+
+### Required vs Optional
+
+All 9 top-level fields (`id`, `category`, `severity`, `title`, `description`, `evidence`, `recommendation`, `verified_by`, `confidence`) are **required**. There are no optional top-level fields in the base schema.
+
+The `evidence` object contains one optional sub-field: `protocol`. This is the first optional sub-field in the schema. Existing gap entries that omit `protocol` remain fully valid.
+
+### Optional Field Validation
+
+The `protocol` sub-field of the `evidence` object is not enum-validated. It accepts any non-empty string when present. Recommended canonical values are `rest`, `graphql`, `grpc`, and `websocket`, but custom strings (e.g., `mqtt`, `soap`, `amqp`) are also accepted without schema changes. When `protocol` is omitted entirely, the gap entry remains valid (backward compatible). When present, an empty string is invalid.
+
+## Budget Control
+
+Each gap entry should average approximately **100 tokens** in structured YAML format (per NFR-024).
+
+Guidelines:
+- Use structured YAML, not prose paragraphs
+- Keep `title` under 80 characters
+- Keep `description` to 1-2 sentences
+- Keep `recommendation` to 1-2 sentences
+- Avoid embedding full code snippets in descriptions — reference via `evidence` instead
+
+With 12 categories across application and infrastructure scans, total token usage varies by project type. After consolidation and deduplication (E11-S10), the single `consolidated-gaps.md` must stay within the 40K framework context budget.
+
+## Examples
+
+### Application Category Example
+
+```yaml
+id: "GAP-config-contradiction-001"
+category: "config-contradiction"
+severity: "high"
+title: "Database timeout mismatch between config files"
+description: "production.yaml sets db.timeout to 30s while docker-compose.yml sets POSTGRES_TIMEOUT to 10s."
+evidence:
+  file: "config/production.yaml"
+  line: 18
+recommendation: "Align timeout values. Set both to 30s or extract to a shared environment variable."
+verified_by: "config-scanner"
+confidence: "high"
+```
+
+### Application Category Example with Protocol
+
+```yaml
+id: "GAP-security-endpoint-001"
+category: "security-endpoint"
+severity: "high"
+title: "Unprotected admin route exposes user management API"
+description: "The /api/admin/users endpoint has no authentication middleware applied."
+evidence:
+  file: "src/routes/admin.ts"
+  line: 15
+  protocol: "rest"
+recommendation: "Add authentication middleware to all /api/admin/* routes."
+verified_by: "security-scanner"
+confidence: "high"
+```
+
+### Infrastructure Category Examples
+
+```yaml
+id: "GAP-resource-drift-001"
+category: "resource-drift"
+severity: "high"
+title: "Terraform state shows orphaned S3 bucket"
+description: "S3 bucket 'app-logs-legacy' exists in AWS but is not declared in any Terraform configuration."
+evidence:
+  file: "infra/terraform/storage.tf"
+  line: "1-45"
+recommendation: "Import the bucket into Terraform state or delete it if no longer needed."
+verified_by: "infra-drift-scanner"
+confidence: "high"
+```
+
+```yaml
+id: "GAP-config-sprawl-001"
+category: "config-sprawl"
+severity: "medium"
+title: "Database port duplicated across 4 config files"
+description: "Port 5432 is hardcoded in Dockerfile, docker-compose.yml, Helm values.yaml, and Terraform variables.tf."
+evidence:
+  file: "docker-compose.yml"
+  line: 14
+recommendation: "Extract database port to a single environment variable, reference it from all 4 files."
+verified_by: "config-sprawl-scanner"
+confidence: "high"
+```
+
+```yaml
+id: "GAP-secret-exposure-001"
+category: "secret-exposure"
+severity: "critical"
+title: "AWS access key embedded in Terraform variables"
+description: "AWS_ACCESS_KEY_ID is set as a default value in variables.tf instead of using a secrets manager."
+evidence:
+  file: "infra/terraform/variables.tf"
+  line: 23
+recommendation: "Remove the default value, use AWS SSM Parameter Store or HashiCorp Vault."
+verified_by: "secret-scanner"
+confidence: "high"
+```
+
+```yaml
+id: "GAP-missing-policy-001"
+category: "missing-policy"
+severity: "medium"
+title: "No policy-as-code enforcement for Kubernetes manifests"
+description: "Kubernetes deployments lack OPA/Gatekeeper or Kyverno policies for security constraints."
+evidence:
+  file: "k8s/deployments/api-server.yaml"
+  line: "1-30"
+recommendation: "Add OPA Gatekeeper constraints or Kyverno policies to enforce pod security standards."
+verified_by: "policy-scanner"
+confidence: "medium"
+```
+
+```yaml
+id: "GAP-environment-skew-001"
+category: "environment-skew"
+severity: "high"
+title: "Staging uses 2 replicas while production uses 5"
+description: "Replica counts differ between staging and production with no documented justification."
+evidence:
+  file: "k8s/overlays/staging/deployment-patch.yaml"
+  line: 8
+recommendation: "Document the replica difference rationale or align staging proportionally."
+verified_by: "env-skew-scanner"
+confidence: "high"
+```

package/_gaia/lifecycle/templates/infra-prd-template.md

@@ -0,0 +1,356 @@
+---
+template: 'infra-prd'
+version: 1.0.0
+used_by: ['create-prd']
+domain: '{domain}'
+---
+
+# Infrastructure PRD: {product_name}
+
+> **Project:** {project_name}
+> **Domain:** {domain}
+> **Date:** {date}
+> **Author:** {agent_name}
+> **Status:** Draft | In Review | Approved
+
+## 1. Overview & Scope
+
+{Platform purpose, target environments, and team ownership.}
+
+### Platform Purpose
+
+{What this infrastructure provides and why it exists.}
+
+### Target Environments
+
+| Environment | Purpose | Region(s) | Owner |
+|-------------|---------|-----------|-------|
+| {env_name} | {purpose} | {regions} | {team} |
+
+### Team Ownership
+
+| Component | Owning Team | Escalation |
+|-----------|-------------|------------|
+| {component} | {team} | {contact} |
+
+## 2. Goals and Non-Goals
+
+### Goals
+- {Goal 1}
+- {Goal 2}
+
+### Non-Goals
+- {Explicitly out of scope item 1}
+
+## 3. Platform Capabilities
+
+{What the infrastructure enables. Each capability follows the format below.}
+
+| ID | Capability | SLO |
+|----|-----------|-----|
+| PC-01 | Enable {team/service} to {capability} with {SLO} | {target} |
+| PC-02 | Enable {team/service} to {capability} with {SLO} | {target} |
+
+## 4. Resource Specifications
+
+{Compute, storage, networking, IAM provisioning. Per-environment breakdown.}
+
+### Compute
+
+| Resource | Environment | Spec | Scaling |
+|----------|-------------|------|---------|
+| {resource} | {env} | {cpu/memory} | {auto/manual, min-max} |
+
+### Storage
+
+| Store | Type | Size | IOPS | Backup |
+|-------|------|------|------|--------|
+| {store} | {block/object/file} | {size} | {iops} | {policy} |
+
+### Networking
+
+| Component | CIDR/Range | Protocol | Purpose |
+|-----------|-----------|----------|---------|
+| {component} | {cidr} | {protocol} | {purpose} |
+
+### IAM Provisioning
+
+| Role/Policy | Scope | Permissions | Lifecycle |
+|-------------|-------|-------------|-----------|
+| {role} | {scope} | {permissions} | {create/rotate/revoke} |
+
+### State Management
+
+{State backend strategy — e.g., Terraform remote state, locking, encryption.}
+
+| Backend | Lock Provider | Encryption | Workspace Strategy |
+|---------|--------------|------------|-------------------|
+| {backend} | {lock} | {encryption} | {workspace} |
+
+### Data Persistence Requirements
+
+| Data Store | Durability | Replication | Retention |
+|------------|-----------|-------------|-----------|
+| {store} | {durability} | {replication} | {retention} |
+
+## 5. Operational SLOs
+
+{Availability targets, MTTR, RTO/RPO, error budgets, resource utilization targets.}
+
+### Availability & Recovery
+
+| Metric | Target | Measurement |
+|--------|--------|-------------|
+| Availability | {99.x%} | {how measured} |
+| MTTR | {minutes} | {how measured} |
+| RTO | {minutes} | {recovery time objective} |
+| RPO | {minutes} | {recovery point objective} |
+| Error Budget | {x% per month} | {how calculated} |
+
+### Resource Utilization Targets
+
+| Resource | Target Utilization | Alert Threshold |
+|----------|-------------------|-----------------|
+| CPU | {target%} | {alert%} |
+| Memory | {target%} | {alert%} |
+| Storage IOPS | {target} | {threshold} |
+| Network Bandwidth | {target Gbps} | {threshold} |
+| Network Latency | {target ms} | {threshold} |
+
+## 6. Security Posture
+
+{Security requirements tailored for infrastructure projects.}
+
+### IAM/RBAC
+
+{Identity and access management, role-based access control policies.}
+
+| Principal | Role | Scope | MFA Required | Review Cadence |
+|-----------|------|-------|-------------|----------------|
+| {principal} | {role} | {scope} | {yes/no} | {quarterly/annually} |
+
+### Network Segmentation
+
+{Network isolation, security groups, firewall rules, zero-trust boundaries.}
+
+| Zone | CIDR | Ingress Rules | Egress Rules | Purpose |
+|------|------|---------------|-------------|---------|
+| {zone} | {cidr} | {rules} | {rules} | {purpose} |
+
+### Secrets Management
+
+{Secrets storage, rotation, injection, and audit strategy.}
+
+| Secret Type | Store | Rotation | Injection Method |
+|-------------|-------|----------|-----------------|
+| {type} | {vault/kms/ssm} | {cadence} | {env var/sidecar/init container} |
+
+### Image Provenance
+
+{Container image signing, scanning, and supply chain verification.}
+
+| Registry | Signing | Scanning | Admission Policy |
+|----------|---------|----------|-----------------|
+| {registry} | {cosign/notary} | {trivy/grype} | {policy} |
+
+### Compliance Mapping
+
+{Regulatory and compliance framework alignment.}
+
+| Framework | Controls | Evidence | Audit Frequency |
+|-----------|----------|----------|----------------|
+| {SOC2/HIPAA/PCI/ISO} | {control IDs} | {how demonstrated} | {cadence} |
+
+## 7. Environment Strategy & Developer Experience
+
+{Environment parity, promotion pipeline, drift detection, self-service provisioning.}
+
+### Environment Parity
+
+| Dimension | Dev | Staging | Production |
+|-----------|-----|---------|-----------|
+| {dimension} | {dev config} | {staging config} | {prod config} |
+
+### Promotion Pipeline
+
+{How changes flow from dev to production.}
+
+```
+{dev} → {staging} → {production}
+```
+
+### Drift Detection
+
+{How configuration drift is detected and remediated.}
+
+| Tool | Schedule | Remediation | Notification |
+|------|----------|-------------|-------------|
+| {tool} | {cron} | {auto/manual} | {channel} |
+
+### Self-Service Provisioning
+
+{Developer self-service capabilities and guardrails.}
+
+| Capability | Interface | Guardrails | Approval |
+|------------|-----------|-----------|----------|
+| {capability} | {CLI/portal/API} | {policy} | {auto/manual} |
+
+### Onboarding
+
+{New team member and new service onboarding procedures.}
+
+### Observability
+
+{Monitoring, logging, tracing, and alerting strategy.}
+
+| Signal | Tool | Retention | Alerting |
+|--------|------|-----------|---------|
+| Metrics | {prometheus/cloudwatch} | {retention} | {pagerduty/slack} |
+| Logs | {elk/cloudwatch} | {retention} | {rules} |
+| Traces | {jaeger/xray} | {retention} | {rules} |
+
+## 8. Dependencies & Provider Constraints
+
+{Cloud provider limits, Terraform provider versions, upstream service contracts.}
+
+### Cloud Provider Limits
+
+| Provider | Service | Limit | Current Usage | Headroom |
+|----------|---------|-------|--------------|----------|
+| {provider} | {service} | {limit} | {current} | {remaining} |
+
+### Terraform Provider Versions
+
+| Provider | Version | Constraint | Notes |
+|----------|---------|-----------|-------|
+| {provider} | {version} | {~> x.y} | {notes} |
+
+### Upstream Service Contracts
+
+| Service | SLA | API Version | Deprecation |
+|---------|-----|------------|-------------|
+| {service} | {sla} | {version} | {date or N/A} |
+
+## 9. Cost Model
+
+{Per-environment resource cost estimates, scaling cost projections, and cost-per-unit efficiency metrics.}
+
+### Per-Environment Resource Cost Estimates
+
+| Resource | Dev (monthly) | Staging (monthly) | Production (monthly) |
+|----------|--------------|-------------------|---------------------|
+| Compute | ${cost} | ${cost} | ${cost} |
+| Storage | ${cost} | ${cost} | ${cost} |
+| Networking | ${cost} | ${cost} | ${cost} |
+| Monitoring | ${cost} | ${cost} | ${cost} |
+| **Total** | **${total}** | **${total}** | **${total}** |
+
+### Scaling Cost Projections
+
+| Scenario | Trigger | Additional Cost | Timeline |
+|----------|---------|----------------|----------|
+| {scenario} | {trigger condition} | ${projection} | {timeframe} |
+
+### Cost-Per-Unit Efficiency Metrics
+
+| Metric | Current | Target | Optimization |
+|--------|---------|--------|-------------|
+| Cost per request | ${cost} | ${target} | {strategy} |
+| Cost per GB stored | ${cost} | ${target} | {strategy} |
+| Cost per environment | ${cost} | ${target} | {strategy} |
+
+## 10. Verification Strategy
+
+{Policy-as-code (OPA/Rego, Checkov, tfsec), plan validation, smoke tests, drift detection, chaos testing.}
+
+### Policy-as-Code
+
+| Tool | Scope | Rules | Enforcement |
+|------|-------|-------|-------------|
+| OPA/Rego | {scope} | {rule count} | {warn/deny} |
+| Checkov | {scope} | {rule count} | {warn/deny} |
+| tfsec | {scope} | {rule count} | {warn/deny} |
+
+### Plan Validation
+
+{Terraform plan review, cost estimation, blast radius analysis.}
+
+| Check | Tool | Gate | Threshold |
+|-------|------|------|-----------|
+| {check} | {tool} | {CI/manual} | {threshold} |
+
+### Smoke Tests
+
+{Post-deployment verification tests.}
+
+| Test | Target | Expected | Timeout |
+|------|--------|----------|---------|
+| {test} | {endpoint/resource} | {result} | {timeout} |
+
+### Drift Detection
+
+{Scheduled plan diffs, state file monitoring, compliance scanning.}
+
+### Chaos Testing
+
+{Failure injection, resilience validation.}
+
+| Experiment | Target | Hypothesis | Blast Radius |
+|-----------|--------|-----------|-------------|
+| {experiment} | {target} | {hypothesis} | {scope} |
+
+## 11. Operational Runbooks
+
+{Scaling, failover, incident response, rollback procedures.}
+
+### Scaling Procedures
+
+| Trigger | Action | Rollback | Owner |
+|---------|--------|----------|-------|
+| {trigger} | {action} | {rollback} | {team} |
+
+### Failover Procedures
+
+| Scenario | Detection | Response | RTO |
+|----------|-----------|----------|-----|
+| {scenario} | {detection} | {response steps} | {rto} |
+
+### Incident Response
+
+| Severity | Notification | Escalation | Runbook |
+|----------|-------------|------------|---------|
+| P1 | {channel} | {escalation path} | {link} |
+| P2 | {channel} | {escalation path} | {link} |
+
+### Rollback Procedures
+
+| Change Type | Rollback Method | Verification | Duration |
+|-------------|----------------|-------------|----------|
+| {type} | {method} | {verification} | {estimate} |
+
+## 12. Requirements Summary
+
+### Infrastructure Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| IR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| IR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Operational Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| OR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| OR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+### Security Requirements
+
+| ID | Description | Priority | Status |
+|----|------------|----------|--------|
+| SR-001 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+| SR-002 | {description} | {Must-Have/Should-Have/Nice-to-Have} | {Draft/Approved} |
+
+## 13. Open Questions
+
+- [ ] {Unresolved question}