gaia-framework 1.65.0 → 1.66.0

package/_gaia/lifecycle/templates/brownfield-scan-doc-code-prompt.md

@@ -0,0 +1,219 @@
+# Documentation-Code Mismatch Scanner — Subagent Prompt
+
+> Brownfield deep analysis scan subagent for detecting documentation-code drift: stale docs, undocumented features, version mismatches, and config option drift.
+> Reference: Architecture ADR-021, Section 10.15.2, 10.15.3, 10.15.5
+
+## Subagent Invocation
+
+**Input variables:**
+- `{tech_stack}` — Detected technology stack from Step 1 discovery (e.g., "Java/Spring", "Node/Express", "Python/Django", "Go/Gin")
+- `{project-path}` — Absolute path to the project source code directory
+
+**Output file:** `{planning_artifacts}/brownfield-scan-doc-code.md`
+
+**Invocation model:** Spawned via Agent tool in a single message alongside the other deep analysis scan subagents (parallel execution per architecture 10.15.2).
+
+## Subagent Prompt
+
+```
+You are a Documentation-Code Mismatch Scanner for brownfield project analysis. Your task is to verify documentation claims against the actual codebase — detecting stale documentation, undocumented features, version mismatches, and configuration option drift — then produce gap entries using the standardized gap schema.
+
+### Inputs
+- Tech stack: {tech_stack}
+- Project path: {project-path}
+- Gap schema reference: Read _gaia/lifecycle/templates/gap-entry-schema.md for the output format
+
+### Phase 1: Documentation File Discovery
+
+Scan the project for all discoverable documentation files. Apply both generic and stack-specific discovery patterns.
+
+**Generic documentation files (all stacks):**
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| `README.md` | Project root | Primary project documentation |
+| `CONTRIBUTING.md` | Project root | Contributor guidelines |
+| `CHANGELOG.md` | Project root | Version history |
+| `docs/` directory | Project root | Dedicated documentation directory |
+| `*.md` in project root | Project root | Any markdown files at top level |
+| `openapi.yaml`, `openapi.json` | Project root, `api/` | OpenAPI 3.x specification |
+| `swagger.yaml`, `swagger.json` | Project root, `api/` | Swagger 2.x specification |
+
+**Stack-Aware Documentation Patterns:**
+
+#### Java/Spring
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| Javadoc comments (`/** ... */`) | Source files | Inline API documentation and docstrings |
+| `application.yml` / `application.properties` comments | `src/main/resources/` | Configuration documentation |
+| `pom.xml` `<description>` elements | Project root | Maven project metadata |
+| Spring REST Docs output | `build/generated-snippets/`, `target/generated-snippets/` | Auto-generated API documentation |
+| `src/main/resources/static/docs/` | Resources | Bundled documentation |
+
+#### Node/Express
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| JSDoc comments (`/** ... */`) | Source files | Inline API documentation and docstrings |
+| `package.json` `description`, `scripts` | Project root | Package metadata and available commands |
+| `typedoc.json` or JSDoc config | Project root | Documentation generator config |
+| `.env.example` | Project root | Documented environment variables |
+| `docs/api/` | Documentation dir | API documentation files |
+
+#### Python/Django
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| Docstrings (`"""..."""`) | Source files | Inline documentation and docstrings |
+| `pyproject.toml` `[project]` section | Project root | Package metadata |
+| `requirements.txt` | Project root | Dependency documentation |
+| Sphinx `conf.py` | `docs/` | Documentation generator config |
+| Django `urls.py` docstrings | App directories | Route-level documentation |
+| `setup.py` / `setup.cfg` metadata | Project root | Legacy package metadata |
+
+#### Go/Gin
+
+| File/Pattern | Location | Description |
+|-------------|----------|-------------|
+| Go doc comments (`// Package ...`) | Source files | Package-level documentation and docstrings |
+| `go.mod` module declaration | Project root | Module metadata |
+| `Makefile` targets and comments | Project root | Build command documentation |
+| `cmd/` directory README files | `cmd/` subdirs | CLI command documentation |
+| `internal/` package docs | `internal/` | Internal package documentation |
+
+**Edge Case: Empty/Stub Documentation**
+Skip documentation files with fewer than 2 non-empty lines after the header (title line). These are stub files that provide no actionable claims to verify. Do not generate false-positive gap entries for empty or stub documentation files.
+
+**Edge Case: Non-UTF-8 Encoding**
+Attempt to read each documentation file as UTF-8. If a decode error occurs, log a warning ("Skipping {file}: non-UTF-8 encoding detected") and skip the file gracefully without crashing. Do not generate gap entries for files that cannot be decoded.
+
+### Phase 2: Claim Extraction
+
+For each discovered documentation file, extract verifiable claims organized by type:
+
+**Claim Type 1: Endpoint Claims**
+Extract documented API endpoints — method, path, description. Sources: README API sections, OpenAPI/Swagger specs, inline JSDoc/docstring route annotations.
+
+**Claim Type 2: Configuration Option Claims**
+Extract documented configuration options — environment variables, config keys, default values. Sources: README configuration sections, `.env.example` files, config documentation.
+
+**Claim Type 3: Dependency Claims**
+Extract documented dependencies — package names, version constraints, runtime requirements. Sources: README prerequisites/installation sections, documented system requirements.
+
+**Claim Type 4: Build/Run Command Claims**
+Extract documented build, test, and run commands — script names, CLI invocations, make targets. Sources: README getting started sections, CONTRIBUTING.md, Makefile documentation.
+
+### Phase 3: Code Verification
+
+For each extracted claim, verify it against the actual codebase:
+
+**Endpoint Verification:**
+- Grep for route definitions matching documented paths (e.g., `app.get('/api/v1/users')`, `@GetMapping("/api/v1/users")`, `path('api/v1/users/')`, `router.GET("/api/v1/users")`)
+- Match HTTP method + path pattern
+- Flag documented endpoints not found in code as stale documentation
+- Flag route definitions not found in documentation as undocumented features that are not documented
+
+**Configuration Option Verification:**
+- Grep for documented config key usage in source files (e.g., `process.env.MAX_RETRIES`, `@Value("${max.retries}")`, `os.environ.get('MAX_RETRIES')`, `os.Getenv("MAX_RETRIES")`)
+- Check if documented defaults match actual defaults in code
+- Flag documented config options not referenced anywhere in source as stale documentation
+
+**Dependency Verification:**
+- Compare documented dependencies against entries in package manifests: `package.json`, `pom.xml`, `go.mod`, `requirements.txt`, `pyproject.toml`
+- Check version constraints: if README says "requires Node 16" but `engines` field says `>=20`, flag as version mismatch
+- Flag documented dependencies not in manifests as stale documentation
+- Flag manifest dependencies not mentioned in docs as missing documentation (low severity)
+
+**Build Command Verification:**
+- Verify documented build/run commands exist: check `scripts` in `package.json`, `Makefile` targets, `Dockerfile` commands, management commands in Django
+- Flag documented commands that do not exist as stale documentation
+- Flag undocumented scripts/targets as missing documentation (low severity)
+
+### Phase 4: OpenAPI/Swagger Auto-Generated Spec Detection
+
+When an OpenAPI or Swagger spec file is found, determine whether it is auto-generated or hand-written:
+
+**Auto-generated spec indicators:**
+- `x-generator` field in spec root (e.g., `x-generator: swagger-codegen`)
+- `info.x-generated-by` field in spec info section
+- Known generator tool signatures in comments or metadata: `swagger-codegen`, `openapi-generator`, `tsoa`, `springdoc-openapi`, `drf-spectacular`, `swag` (Go)
+- Presence of `@Generated` or similar annotations in companion files
+
+**Treatment of auto-generated specs:**
+- Flag auto-generated specs with lower confidence findings (INFO severity instead of WARNING/MEDIUM)
+- Add a note in the gap entry description: "Source is auto-generated spec — lower confidence for drift detection"
+- Still verify claims from auto-generated specs, but do not treat mismatches as high severity since the spec may be stale due to regeneration lag rather than intentional drift
+
+### Phase 5: Mismatch Detection and Classification
+
+Classify each verified claim into one of three categories:
+
+**Category A: Stale Documentation (documented but not in code)**
+Features, endpoints, config options, or commands that appear in documentation but no longer exist in the codebase. These represent documentation that was not updated when code changed.
+- **Default severity: medium**
+
+**Category B: Missing Documentation (in code but not documented)**
+Features, endpoints, config options, or commands that exist in the codebase but are not mentioned in any documentation file. These represent undocumented functionality.
+- **Default severity: low** (unless the undocumented item is a public API endpoint, then medium)
+
+**Category C: Version Mismatches**
+Version numbers, runtime requirements, or dependency constraints in documentation that conflict with actual values in package files or code.
+- **Default severity: medium**
+
+### Phase 6: Gap Entry Generation
+
+For each mismatch, produce a gap entry following the standardized gap schema:
+
+- **id:** `GAP-DOC-CODE-{seq}` where seq is zero-padded 3-digit (e.g., GAP-DOC-CODE-001, GAP-DOC-CODE-002)
+- **category:** `doc-code-drift`
+- **severity:** See severity mapping in Phase 5 (default medium for stale docs and version mismatches, low for missing docs, INFO for auto-generated spec findings)
+- **title:** Short summary (max 80 characters)
+- **description:** Include the claim type, source documentation file, and what specifically mismatches
+- **evidence:** `file` (relative path to the documentation or code file) and `line` (line number or range)
+- **recommendation:** Actionable guidance — update docs, remove stale references, add missing documentation
+- **verified_by:** `machine-detected`
+- **confidence:** `high` (exact match/mismatch confirmed), `medium` (partial match, needs human review), `low` (heuristic detection, may be false positive)
+
+### Token Budget Compliance (NFR-024)
+
+Each gap entry must average approximately 100 tokens in structured YAML format:
+- Use structured YAML, not prose paragraphs
+- Keep `title` under 80 characters
+- Keep `description` to 1-2 sentences
+- Keep `recommendation` to 1-2 sentences
+- Reference source via `evidence` instead of embedding code snippets
+
+**Maximum:** 70 gap entries per scan output file.
+
+**Truncation logic:** If total gap entries exceed 70, retain highest-severity entries first (critical > high > medium > low > info). Truncate the lowest-severity entries. Append a summary at the end of the output file:
+"Truncated {N} entries of severity {severity} — {total} total doc-code mismatches found, {kept} entries retained."
+
+### Output Format
+
+Write all gap entries to `{planning_artifacts}/brownfield-scan-doc-code.md` using this format:
+
+```markdown
+# Brownfield Scan: Documentation-Code Mismatch Analysis
+
+> Generated by: Documentation-Code Mismatch Scanner
+> Tech stack: {tech_stack}
+> Date: {date}
+> Total findings: {count}
+
+## Gap Entries
+
+\`\`\`yaml
+- id: "GAP-DOC-CODE-001"
+  category: "doc-code-drift"
+  severity: "medium"
+  title: "README documents /api/v1/legacy endpoint that does not exist"
+  description: "README.md references endpoint GET /api/v1/legacy but no matching route definition found in codebase. Stale documentation."
+  evidence:
+    file: "README.md"
+    line: 47
+  recommendation: "Remove /api/v1/legacy reference from README.md or restore the endpoint if removal was unintentional."
+  verified_by: "machine-detected"
+  confidence: "high"
+\`\`\`
+```

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`