gaia-framework 1.65.1 → 1.83.2

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

@@ -0,0 +1,169 @@
+# Hard-Coded Business Logic Scanner — Subagent Prompt
+
+> Brownfield deep analysis scan subagent. Detects hard-coded business logic values that should be externalized to configuration.
+> 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 identify hard-coded business logic values embedded in source code. These are values that represent business rules, configuration, or environment-specific settings and should be externalized to configuration files, environment variables, or feature flags.
+
+**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
+
+Scan for the following 6 categories of hard-coded values:
+
+### 1. Magic Numbers in Business Calculations
+
+Values used in business logic that represent thresholds, limits, rates, or quantities.
+
+**Flag these:**
+- Numeric thresholds in business conditions: `if (amount > 10000)`
+- Hard-coded retry counts in business logic: `maxRetries = 3`
+- Hard-coded pagination limits: `const PAGE_SIZE = 50`
+- Timeout values embedded in business logic: `setTimeout(callback, 30000)`
+
+### 2. Hard-coded URLs and Endpoints
+
+URLs, API endpoints, and service addresses embedded directly in source code.
+
+**Flag these:**
+- Production/staging URLs: `fetch("https://api.prod.example.com/v2")`
+- Hard-coded service endpoints: `const API_BASE = "https://internal.service.com"`
+- Database connection strings with hostnames: `mongodb://prod-db:27017`
+
+### 3. Embedded SQL Queries with Business Rules
+
+SQL queries containing hard-coded business logic values.
+
+**Flag these:**
+- Hard-coded role/status values in WHERE clauses
+- Business tier filtering with literal strings
+- Hard-coded date boundaries
+
+### 4. Date/Time Thresholds
+
+Hard-coded dates, times, or durations that represent business policy.
+
+### 5. Pricing and Rate Values
+
+Monetary values, percentages, rates, or financial thresholds embedded in code.
+
+### 6. Role and Permission Strings
+
+Hard-coded role names, permission identifiers, or authorization strings.
+
+## Detection Categories — Infrastructure Patterns (E12-S6)
+
+**Apply ONLY when {project_type} is `infrastructure` or `platform`.**
+
+### 7. Hard-Coded IP Addresses in Infrastructure Files
+
+Detect IP addresses embedded directly in IaC, Kubernetes manifests, and network configuration.
+
+**Flag these:**
+- IPv4 addresses in Terraform configs: `cidr_block = "10.0.1.0/24"` with specific IPs (not CIDR ranges for subnets)
+- Hard-coded IPs in Kubernetes Services or Endpoints: `clusterIP: "10.96.0.10"`
+- Static IPs in Helm values: `loadBalancerIP: "203.0.113.50"`
+- Hard-coded DNS entries: `server = "10.0.0.53"` instead of using service discovery
+- IPs in security group rules: `cidr_blocks = ["203.0.113.0/32"]`
+
+**Do NOT flag:**
+- Standard CIDR ranges for VPC/subnet definitions: `10.0.0.0/16`, `172.16.0.0/12`
+- Loopback addresses: `127.0.0.1`, `0.0.0.0`
+- Kubernetes internal DNS: `kube-dns`, `coredns`
+
+**Gap category:** `hard-coded-logic` with infra context in description
+
+### 8. Magic Port Numbers in Infrastructure
+
+Detect non-standard or undocumented port numbers in infrastructure configuration.
+
+**Flag these:**
+- Non-standard port numbers without documentation: `containerPort: 8443`, `hostPort: 9999`
+- Port numbers that differ between service and deployment: `port: 80` in Service but `containerPort: 8080` in Pod
+- Hard-coded port ranges in security groups: `from_port = 30000, to_port = 32767`
+- Port numbers in environment variables with literal values: `PORT=3001`
+
+**Do NOT flag:**
+- Well-known ports with standard usage: 80 (HTTP), 443 (HTTPS), 22 (SSH), 5432 (PostgreSQL), 3306 (MySQL), 6379 (Redis), 27017 (MongoDB)
+- Ports defined in variables/config and referenced: `var.app_port`
+
+**Gap category:** `hard-coded-logic` with infra context in description
+
+### 9. Embedded Secrets and Credential Patterns
+
+Detect secrets, credentials, AMI IDs, and sensitive values embedded in IaC or config files.
+
+**Flag these (critical severity):**
+- AWS access keys: patterns matching `AKIA[0-9A-Z]{16}` in any file
+- AWS secret keys: base64-like strings assigned to `secret_key` or `aws_secret_access_key`
+- API tokens in config: `token = "ghp_..."`, `api_key = "sk-..."`
+- Database passwords in plaintext: `password = "mysecretpassword"` in tfvars or values.yaml
+- SSH private keys embedded in configs or user-data scripts
+
+**Flag these (high severity):**
+- AMI IDs hard-coded: `ami = "ami-0abcdef1234567890"` — should use data source or variable
+- Docker image tags with specific SHA: `image: myapp@sha256:abc123` when not pinned intentionally
+- Hard-coded AWS account IDs: `account_id = "123456789012"`
+- Hard-coded region strings: `region = "us-east-1"` without variable reference
+
+**Gap category:** `hard-coded-logic` (or escalate to `secret-exposure` for actual credentials)
+
+### 10. Hard-Coded Resource Limits in Infrastructure
+
+Detect hard-coded CPU and memory limits in Kubernetes manifests, Terraform configs, and Docker files.
+
+**Flag these:**
+- Kubernetes resource requests/limits with literal values:
+  ```yaml
+  resources:
+    requests:
+      cpu: "500m"
+      memory: "512Mi"
+    limits:
+      cpu: "1000m"
+      memory: "1Gi"
+  ```
+  These should reference Helm values or kustomize patches for environment-specific tuning.
+- Terraform instance types hard-coded: `instance_type = "t3.medium"` — should be a variable
+- Docker memory limits: `--memory="2g"` in compose files without variable reference
+- Auto-scaling thresholds: `min_size = 2, max_size = 10` without variables
+- EBS volume sizes: `size = 100` without variable reference
+
+**Do NOT flag:**
+- Resource values defined in Helm values.yaml (already externalized)
+- Resource values in Terraform variables (already parameterized)
+- Default values in variable blocks with clear documentation
+
+**Gap category:** `hard-coded-logic` with infra context in description
+
+## Acceptable Constant Allowlist
+
+Do NOT flag: HTTP status codes, math constants, array indices, standard library constants, test fixture data.
+
+## Stack-Aware Detection Patterns
+
+Apply framework-specific patterns based on {tech_stack} (Java/Spring, Node/Express, Python/Django, Go/Gin) as documented in the original E11-S4 specification.
+
+## False Positive Suppression Rules
+
+- Configuration files (.yml, .yaml, .properties, .env) are externalized — do not flag
+- Test files contain legitimate test fixtures — skip
+- Framework-specific externalization patterns (Spring @Value, process.env, Django settings) — do not flag
+
+## Output Format
+
+Gap entry structure uses `category: "hard-coded-logic"` with `id: "GAP-HARDCODED-{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-hardcoded.md`

package/_gaia/lifecycle/templates/brownfield-scan-integration-seam-prompt.md

@@ -0,0 +1,127 @@
+# Integration Seam Analyzer — Subagent Prompt
+
+> Brownfield deep analysis scan subagent. Traces data flows across service boundaries and detects fragile integration points.
+> 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 trace data flows across service boundaries, detect fragile integration points, tight coupling, and missing contracts. For infrastructure projects, additionally map service mesh topology, ingress/egress routes, and cross-namespace dependencies.
+
+**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. HTTP Client Calls (Service-to-Service)
+
+Detect outbound HTTP/REST calls:
+- **Java/Spring:** Feign clients, RestTemplate, WebClient, HttpClient
+- **Node/Express:** axios, fetch, got, node-fetch, superagent
+- **Python/Django:** requests, httpx, urllib3, aiohttp
+- **Go:** net/http.Client, resty, go-retryablehttp
+
+### 2. Message Queue Integration
+
+Detect message queue producers/consumers:
+- Bull, BullMQ, RabbitMQ (amqplib), Kafka (kafkajs, confluent-kafka), Celery, SQS, NATS
+
+### 3. Database Shared Access
+
+Detect multiple services or modules accessing the same database tables.
+
+### 4. Coupling Classification
+
+Classify coupling issues:
+- Tightly coupled: shared DB tables, direct internal API calls
+- Missing circuit breaker or retry logic
+- Undocumented external service dependencies
+- Inconsistent serialization formats
+
+### 5. Dependency Graph
+
+Generate adjacency list showing service-to-service relationships with connection type and direction.
+
+## Detection Categories — Infrastructure Patterns (E12-S6)
+
+**Apply ONLY when {project_type} is `infrastructure` or `platform`.**
+
+### 6. Service Mesh Topology Mapping
+
+Detect and map service mesh configurations and their routing rules.
+
+**Scan for:**
+- **Istio:** VirtualService, DestinationRule, Gateway, ServiceEntry, PeerAuthentication
+  - `kind: VirtualService` — extract routing rules, traffic splitting percentages, timeout configs
+  - `kind: DestinationRule` — extract load balancing policies, circuit breaker settings, TLS modes
+  - `kind: Gateway` — extract ingress listeners, TLS configuration, host matching
+  - `kind: ServiceEntry` — extract external service registrations
+  - `kind: PeerAuthentication` — extract mTLS modes (STRICT, PERMISSIVE, DISABLE)
+- **Linkerd:** ServiceProfile, TrafficSplit, Server, ServerAuthorization
+- **Consul Connect:** ServiceIntention, ServiceRouter, ServiceSplitter, ServiceResolver
+
+**Flag these as gaps:**
+- VirtualService without timeout configuration (unbounded request duration)
+- DestinationRule without circuit breaker settings (no fault isolation)
+- PeerAuthentication in PERMISSIVE mode in production (allows plaintext traffic)
+- ServiceEntry for external services without failover configuration
+- Traffic splitting percentages that do not sum to 100%
+- Missing retryOn policies for transient failure codes (5xx, connect-failure)
+
+**Severity:** `high` for missing circuit breakers and timeouts, `medium` for permissive mTLS
+
+### 7. Ingress/Egress Route Mapping
+
+Map all ingress and egress routes to understand traffic flow in and out of the cluster.
+
+**Scan for:**
+- Kubernetes Ingress resources: hosts, paths, backend services, TLS config
+- Istio Gateway + VirtualService pairs: external entry points into the mesh
+- AWS ALB Ingress Controller annotations: `alb.ingress.kubernetes.io/*`
+- Nginx Ingress Controller annotations: `nginx.ingress.kubernetes.io/*`
+- Egress rules: NetworkPolicy egress, Istio ServiceEntry for external services, Calico GlobalNetworkPolicy
+- NAT Gateway / Internet Gateway configurations in Terraform
+
+**Flag these as gaps:**
+- Ingress routes without TLS/HTTPS enforcement
+- Ingress to services that are also exposed via NodePort (dual exposure)
+- Missing egress restrictions (all outbound traffic allowed by default)
+- External service dependencies without explicit ServiceEntry or egress policy
+- Ingress paths that bypass the service mesh (direct NodePort access)
+
+**Severity:** `high` for missing TLS and unrestricted egress, `medium` for dual exposure
+
+### 8. Cross-Namespace Dependency Detection
+
+Detect service dependencies that span Kubernetes namespaces.
+
+**Scan for:**
+- Service references using FQDN: `{service}.{namespace}.svc.cluster.local`
+- ExternalName services pointing to other namespaces
+- NetworkPolicy rules referencing `namespaceSelector`
+- Istio VirtualService/DestinationRule targeting services in other namespaces
+- ConfigMap or Secret references from other namespaces (via volume mounts or env)
+- ServiceAccount tokens shared across namespaces
+
+**Flag these as gaps:**
+- Cross-namespace service calls without NetworkPolicy allowing the traffic
+- Cross-namespace dependencies without documented ownership or SLA
+- Hardcoded namespace names in service URLs (fragile to namespace renaming)
+- Cross-namespace secret sharing without RBAC scoping
+- Circular cross-namespace dependencies (A -> B -> A)
+
+**Severity:** `high` for undocumented cross-namespace dependencies, `medium` for hardcoded namespaces
+
+## Output Format
+
+Gap entry structure uses `category: "integration-seam"` with `id: "GAP-INTEGRATION-{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-integration-seam.md`

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`