gaia-framework 1.65.1 → 1.66.0

package/_gaia/lifecycle/templates/brownfield-scan-runtime-behavior-prompt.md

@@ -0,0 +1,141 @@
+# Runtime Behavior Inventory Scanner — Subagent Prompt
+
+> Brownfield deep analysis scan subagent. Catalogs runtime behaviors that only manifest during execution.
+> Reference: Architecture ADR-021, Section 10.15.2, Section 10.15.5, ADR-022 §10.16.5
+> Infra-awareness: E12-S6 — applies infra-specific patterns when project_type is infrastructure or platform.
+
+## Objective
+
+Scan the codebase at `{project-path}` to catalog runtime behaviors — scheduled tasks, background processes, startup hooks, shutdown handlers, and behaviors that are not visible from static code structure alone.
+
+**Input variables:**
+- `{tech_stack}` — Detected technology stack from Step 1 discovery
+- `{project-path}` — Absolute path to the project source code directory
+- `{project_type}` — Project type: `application`, `infrastructure`, or `platform`
+
+**Output format:** Follow the gap entry schema at `{project-root}/_gaia/lifecycle/templates/gap-entry-schema.md` exactly.
+
+## Detection Categories — Application Patterns
+
+### 1. Scheduled Tasks and Cron Jobs
+
+Detect application-level scheduled tasks:
+- **Java/Spring:** `@Scheduled`, `@EnableScheduling`, Quartz `@DisallowConcurrentExecution`
+- **Node/Express:** `node-cron`, `agenda`, `bull` queue scheduled jobs, `setInterval` for polling
+- **Python/Django:** Celery `@periodic_task`, `celery.conf.beat_schedule`, `django-crontab`
+- **Go:** `robfig/cron`, `time.Ticker`, goroutine polling loops
+
+### 2. Startup and Shutdown Hooks
+
+Detect application lifecycle hooks:
+- **Java/Spring:** `@PostConstruct`, `@PreDestroy`, `ApplicationListener`, `CommandLineRunner`
+- **Node/Express:** `process.on('SIGTERM')`, `process.on('SIGINT')`, `beforeExit`
+- **Python/Django:** `AppConfig.ready()`, `atexit.register`, signal handlers
+- **Go:** `os.Signal` handling, `defer` patterns in main(), `sync.Once`
+
+### 3. Background Workers and Async Processors
+
+Detect background processing patterns:
+- Message queue consumers (Bull, SQS, Kafka, RabbitMQ consumers)
+- Worker threads, child processes, goroutines for long-running tasks
+- WebSocket connection handlers
+- File watchers and directory monitors
+
+### 4. Race Conditions and Concurrency Risks
+
+Detect patterns prone to race conditions:
+- Shared mutable state without synchronization
+- Non-atomic read-modify-write sequences
+- Missing database transaction boundaries on multi-step operations
+
+## Detection Categories — Infrastructure Patterns (E12-S6)
+
+**Apply ONLY when {project_type} is `infrastructure` or `platform`.**
+
+### 5. CronJob Detection
+
+Detect Kubernetes CronJob resources and their scheduling patterns.
+
+**Scan for:**
+- `kind: CronJob` in Kubernetes manifests
+- `spec.schedule` field — extract the cron expression
+- `spec.concurrencyPolicy` — flag if missing (defaults to `Allow`, may cause overlapping runs)
+- `spec.startingDeadlineSeconds` — flag if missing (no deadline for missed schedules)
+- `spec.successfulJobsHistoryLimit` / `spec.failedJobsHistoryLimit` — flag if set to 0 (no history retained)
+- `spec.suspend` — note if suspended (informational)
+
+**Flag these as gaps:**
+- CronJobs without `concurrencyPolicy: Forbid` or `Replace` (risk of overlapping runs)
+- CronJobs without `startingDeadlineSeconds` (missed jobs may accumulate)
+- CronJobs without resource limits on their pod template
+- CronJobs with `restartPolicy: Always` (CronJob pods should use `OnFailure` or `Never`)
+
+**Severity:** `medium` for missing policies, `high` for incorrect restart policies
+
+### 6. DaemonSet Detection
+
+Detect Kubernetes DaemonSet resources and their node scheduling.
+
+**Scan for:**
+- `kind: DaemonSet` in Kubernetes manifests
+- `spec.updateStrategy` — flag if missing or set to `OnDelete` (prefer `RollingUpdate`)
+- `spec.template.spec.tolerations` — catalog which node taints are tolerated
+- `spec.template.spec.nodeSelector` — catalog node selection criteria
+- `spec.template.spec.priorityClassName` — note if using system priority classes
+
+**Flag these as gaps:**
+- DaemonSets without `updateStrategy` (defaults to `OnDelete`, requires manual pod deletion)
+- DaemonSets without resource requests/limits (can starve node resources)
+- DaemonSets with `hostNetwork: true` without documented justification
+- DaemonSets without `terminationGracePeriodSeconds` set appropriately
+
+**Severity:** `medium` for missing update strategy, `high` for unbounded resource usage
+
+### 7. Init Container and Sidecar Pattern Detection
+
+Detect init containers and sidecar container patterns in Kubernetes Pods.
+
+**Scan for:**
+- `spec.initContainers` in Pod specs — catalog each init container's purpose
+- Multi-container pods where one container serves as a sidecar (log collector, proxy, metrics agent)
+- Istio/Envoy sidecar injection annotations: `sidecar.istio.io/inject: "true"`
+- Init containers that run database migrations, config loading, or secret fetching
+- Sidecar containers for: logging (fluentd, filebeat), monitoring (prometheus exporter), proxying (envoy, nginx)
+
+**Flag these as gaps:**
+- Init containers without resource limits (can block pod startup indefinitely)
+- Init containers without timeout or failure handling
+- Sidecar containers without health checks (liveness/readiness probes)
+- Multi-container pods without clear documentation of container roles
+
+**Severity:** `medium` for missing resource limits, `low` for missing documentation
+
+### 8. Health Probe Detection (Liveness, Readiness, Startup)
+
+Detect the presence and configuration of Kubernetes health probes.
+
+**Scan for:**
+- `livenessProbe` — checks if the container is running; restarts on failure
+- `readinessProbe` — checks if the container can serve traffic; removes from service on failure
+- `startupProbe` — checks if the application has started; disables liveness/readiness until success
+
+**Flag these as gaps:**
+- Containers without `livenessProbe` (no automatic restart on hang)
+- Containers without `readinessProbe` (may receive traffic before ready)
+- Long-starting containers without `startupProbe` (liveness probe may kill them during startup)
+- Probes with `initialDelaySeconds: 0` and no `startupProbe` (may restart healthy containers during startup)
+- Probes using `exec` commands that could be expensive (e.g., database queries as health checks)
+- Liveness and readiness probes pointing to the same endpoint (if the endpoint is slow, both fail simultaneously)
+- Missing `periodSeconds`, `timeoutSeconds`, `failureThreshold` customization (relying on defaults may not suit the workload)
+
+**Severity:** `high` for missing liveness/readiness probes, `medium` for suboptimal probe configuration
+
+## Output Format
+
+Gap entry structure uses `category: "runtime-behavior"` with `id: "GAP-RUNTIME-{seq}"`.
+For infra-specific findings, include "[INFRA]" prefix in the title for clarity.
+Budget: max 70 entries, truncate low-severity if exceeded.
+
+## Output File
+
+Write all findings to: `{planning_artifacts}/brownfield-scan-runtime-behavior.md`

package/_gaia/lifecycle/templates/brownfield-scan-security-prompt.md

@@ -0,0 +1,212 @@
+# Security Endpoint Audit Scanner — Subagent Prompt
+
+> Brownfield deep analysis scan subagent. Detects security gaps in API endpoints and infrastructure security configurations.
+> Reference: Architecture ADR-021, Section 10.15.2, Section 10.15.5, ADR-022 §10.16.5
+> Infra-awareness: E12-S6 — applies infra-specific patterns when project_type is infrastructure or platform.
+
+## Objective
+
+Scan the codebase at `{project-path}` to catalog all API endpoints and infrastructure security configurations, and identify security gaps.
+
+**Input variables:**
+- `{tech_stack}` — Detected technology stack from Step 1 discovery
+- `{project-path}` — Absolute path to the project source code directory
+- `{project_type}` — Project type: `application`, `infrastructure`, or `platform`
+
+**Output format:** Follow the gap entry schema at `{project-root}/_gaia/lifecycle/templates/gap-entry-schema.md` exactly.
+
+## Phase 1: Endpoint Discovery (Application Patterns)
+
+Catalog all API endpoints. For each endpoint, record: route path, HTTP method, authentication, authorization, handler function.
+
+### Stack-Aware Endpoint Discovery Patterns
+
+Apply framework-specific patterns based on {tech_stack}:
+
+#### Java/Spring
+- `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`, `@PatchMapping`
+- `@RequestMapping(method = RequestMethod.GET)`
+- `RouterFunction<ServerResponse>` (Spring WebFlux)
+- `@RestController` class-level `@RequestMapping`
+
+#### Node/Express
+- `app.get()`, `app.post()`, `app.put()`, `app.delete()`, `app.patch()`
+- `router.get()`, `router.post()`, `router.put()`, `router.delete()`
+- `app.route().get().post()`
+- `app.all()`
+
+#### Python/Django
+- `path()`, `re_path()` in `urls.py`
+- `@api_view(['GET', 'POST'])`
+- `class XxxViewSet(viewsets.ModelViewSet)`
+- `class XxxView(APIView)`
+
+#### Go/Gin
+- `r.GET()`, `r.POST()`, `r.PUT()`, `r.DELETE()`, `r.PATCH()`
+- `group.GET()`, `group.POST()`
+- `http.HandleFunc()`, `http.Handle()`
+- `mux.HandleFunc()`, `mux.Handle()`
+
+### Graceful Exit — No API Endpoints
+
+If no API endpoints are detected, output a summary note and zero gap entries for the application phase.
+
+## Phase 2: Security Gap Detection — Application Rules
+
+### 1. Missing Authentication Middleware (AC3a)
+
+Detect endpoints with no authentication middleware. Mutating endpoints (POST, PUT, PATCH, DELETE) missing auth are `critical`. Read endpoints (GET) missing auth that return non-public data are `high`.
+
+### 2. IDOR Vulnerability Detection (AC3b)
+
+Detect endpoints where path parameters reference resources without ownership validation. IDOR vulnerabilities are `critical` severity.
+
+### 3. Rate Limiting Gap Detection (AC3c)
+
+Detect endpoints without rate limiting at the application level. Missing rate limiting is `high` severity.
+
+**Note:** Reverse proxy or API gateway rate limiting is not visible to static code analysis. Verify infrastructure-level rate limiting separately.
+
+### 4. Sensitive Data Exposure Detection (AC3d)
+
+Detect endpoints whose response objects contain fields that should be filtered:
+- `password`, `password_hash`, `hashed_password`
+- `token`, `access_token`, `refresh_token`, `api_key`, `secret`
+- `ssn`, `social_security`, `national_id`
+- `credit_card`, `card_number`, `cvv`, `expiry`
+- Any field matching patterns: `*_secret`, `*_key`, `*_token`
+
+Sensitive data exposure is `high` severity.
+
+### 5. Missing Input Validation on Mutating Endpoints (AC3e)
+
+Detect POST/PUT/PATCH/DELETE endpoints that accept a request body but have no input validation. Missing input validation is `high` severity.
+
+## Phase 3: False-Positive Mitigation — Inherited Auth
+
+Before flagging an endpoint as "missing authentication middleware," trace the middleware chain upward:
+
+#### Java/Spring Security
+- `HttpSecurity.authorizeRequests().anyRequest().authenticated()` — app-level
+- `@PreAuthorize` on controller class — class-level
+- `SecurityFilterChain` bean — app-level
+- `.antMatchers("/api/**").authenticated()` — path-level
+
+#### Node/Express Middleware
+- `app.use(authMiddleware)` — app-level
+- `router.use(passport.authenticate('jwt'))` — router-level
+- `app.use('/api', authMiddleware, apiRouter)` — path-level
+
+#### Django Permissions
+- `REST_FRAMEWORK.DEFAULT_PERMISSION_CLASSES: [IsAuthenticated]` — app-level
+- `LoginRequiredMixin` — class-level
+- `@login_required` — function-level
+
+#### Go/Gin Middleware
+- `r.Use(JWTAuth())` — app-level
+- `group := r.Group("/api"); group.Use(AuthMiddleware())` — group-level
+
+## Phase 4: Infrastructure Security Patterns (E12-S6)
+
+**Apply ONLY when {project_type} is `infrastructure` or `platform`.**
+
+### 4a. Exposed Ports in Kubernetes Manifests
+
+Detect Kubernetes Services and Pods that expose ports unnecessarily or without documentation.
+
+**Flag these:**
+- `NodePort` services exposing ports to external traffic without documented justification
+- `hostPort` usage in Pod specs (exposes container port on the node's IP)
+- Services with `type: LoadBalancer` without IP whitelisting or security group restrictions
+- Pods with `hostNetwork: true` (shares the node's network namespace)
+- Containers listening on privileged ports (< 1024) without documented need
+
+**Severity:** `high` for NodePort/LoadBalancer exposure, `critical` for hostNetwork/hostPort
+
+### 4b. Permissive Ingress Rules
+
+Detect overly permissive network ingress rules in Kubernetes Ingress resources, cloud security groups, and firewall rules.
+
+**Flag these:**
+- Kubernetes Ingress resources without TLS configuration
+- Ingress rules with wildcard hosts: `host: "*"` or missing host field
+- AWS Security Groups with `0.0.0.0/0` ingress on non-standard ports
+- Terraform `aws_security_group_rule` with `cidr_blocks = ["0.0.0.0/0"]` on ports other than 80/443
+- GCP firewall rules with `source_ranges = ["0.0.0.0/0"]` without service account filtering
+- Azure NSG rules with `source_address_prefix = "*"` on sensitive ports
+
+**Severity:** `critical` for `0.0.0.0/0` on sensitive ports (SSH/22, DB/3306/5432, admin ports), `high` for permissive ingress on standard ports
+
+### 4c. Overly Broad RBAC Bindings
+
+Detect Kubernetes RBAC configurations that grant excessive permissions.
+
+**Flag these:**
+- `ClusterRoleBinding` bound to `cluster-admin` for non-system service accounts
+- `RoleBinding` or `ClusterRoleBinding` with `resources: ["*"]` and `verbs: ["*"]`
+- Service accounts with `automountServiceAccountToken: true` when not needed
+- `ClusterRole` with `apiGroups: ["*"]` granting access to all API groups
+- Roles that grant `create`, `delete`, or `patch` on `secrets` without namespace scoping
+- Default service account with non-default permissions
+
+**Severity:** `critical` for cluster-admin bindings and wildcard permissions, `high` for broad secret access
+
+### 4d. Missing NetworkPolicy
+
+Detect Kubernetes namespaces and workloads without NetworkPolicy enforcement.
+
+**Flag these:**
+- Namespaces with no NetworkPolicy resources defined (all traffic allowed by default)
+- Pods in namespaces where NetworkPolicy exists but does not select them (via label selectors)
+- NetworkPolicy with empty `ingress` or `egress` rules (allows all traffic of that type)
+- Workloads in production namespaces without both ingress AND egress NetworkPolicy
+- Multi-tenant clusters without namespace-level network isolation
+
+**Severity:** `high` for missing NetworkPolicy in production, `medium` for missing in non-production
+
+## Output Format
+
+### Gap Entry Structure
+
+Each finding MUST use the standardized gap schema from `gap-entry-schema.md`:
+
+```yaml
+gap:
+  id: "GAP-SECURITY-{seq}"
+  category: "security-endpoint"
+  severity: "{critical|high}"
+  title: "Short description (max 80 chars)"
+  description: "What was found, why it matters, what security implication it has"
+  evidence:
+    file: "relative/path/to/file"
+    line: 42
+  recommendation: "Actionable fix — add middleware, validate input, filter response"
+  verified_by: "machine-detected"
+  confidence: "{high|medium|low}"
+```
+
+### Confidence Classification
+
+- **high** — exact pattern match (e.g., no auth decorator/annotation on a `@PostMapping` handler)
+- **medium** — heuristic match (e.g., handler accesses path parameter without obvious ownership check)
+- **low** — ambiguous case (e.g., custom auth mechanism not recognized by pattern table)
+
+### Budget Enforcement
+
+Each gap entry should average approximately 100 tokens in structured YAML format.
+Maximum output: 70 gap entries per scan.
+
+If more than 70 gaps are detected:
+1. Sort all findings by severity (critical > high)
+2. Within same severity, sort by confidence (high > medium > low)
+3. Keep the top 70 entries
+4. Append a budget summary section:
+
+```markdown
+## Budget Summary
+Total gaps detected: {N}. Showing top 70 by severity. Omitted: {N-70} entries.
+```
+
+## Output File
+
+Write all findings to: `{planning_artifacts}/brownfield-scan-security.md`

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

@@ -0,0 +1,247 @@
+# Gap Entry Schema
+
+> **Version:** 1.1.0
+> **Story:** E11-S1, E12-S5
+> **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>
+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 (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
+```
+
+Or with a line range:
+
+```yaml
+evidence:
+  file: "config/database.yml"
+  line: "15-28"                   # Line range (start-end)
+```
+
+| 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 |
+
+## 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
+
+### Required vs Optional
+
+All 9 fields (`id`, `category`, `severity`, `title`, `description`, `evidence`, `recommendation`, `verified_by`, `confidence`) are **required**. There are no optional fields in the base schema.
+
+## 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"
+```
+
+### 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"
+```