gaia-framework 1.65.1 → 1.66.0

package/_gaia/lifecycle/skills/document-rulesets.md

@@ -1,17 +1,35 @@
 ---
 name: document-rulesets
-version: '1.0'
+version: '1.1'
 applicable_agents: [validator]
-description: 'Document-specific validation rulesets for artifact type detection, structural quality checks per artifact type, and two-pass validation logic.'
-sections: [type-detection, prd-rules, arch-rules, ux-rules, test-plan-rules, epics-rules, two-pass-logic]
+description: 'Document-specific validation rulesets for artifact type detection (path and frontmatter), structural quality checks per artifact type (application, infrastructure, platform PRDs), and two-pass validation logic.'
+sections: [type-detection, prd-rules, infra-prd-rules, platform-prd-rules, arch-rules, ux-rules, test-plan-rules, epics-rules, two-pass-logic]
 ---
 
 <!-- SECTION: type-detection -->
 ## Artifact Type Detection
 
-### Path-to-Ruleset Mapping
+### Frontmatter-Based Detection (Higher Priority)
 
-Detect the artifact type from the file path basename. Match against these patterns:
+Check frontmatter first before falling back to filename detection. If the artifact has YAML frontmatter with a `template` field, use the frontmatter mapping table below. Frontmatter detection takes higher priority than filename detection because it is explicit and unambiguous.
+
+| Frontmatter `template` Value | Ruleset ID(s) | Description |
+|------------------------------|---------------|-------------|
+| `'prd'` | prd-rules | Application Product Requirements Document |
+| `'infra-prd'` | infra-prd-rules | Infrastructure PRD |
+| `'platform-prd'` | prd-rules + infra-prd-rules | Platform PRD (both rulesets applied) |
+
+### Frontmatter Detection Algorithm
+
+1. Parse the artifact's YAML frontmatter (content between opening `---` and closing `---`)
+2. Check for a `template` field in the frontmatter
+3. If `template` field exists, match against the frontmatter mapping table above
+4. If a match is found, return the corresponding ruleset ID(s). For `'platform-prd'`, return both `prd-rules` and `infra-prd-rules` — both rulesets are applied sequentially
+5. If `template` field is absent or does not match, fall through to path-based detection below
+
+### Path-to-Ruleset Mapping (Fallback)
+
+If no frontmatter match is found, detect the artifact type from the file path basename. Match against these patterns:
 
 | File Pattern | Ruleset ID | Description |
 |-------------|------------|-------------|
@@ -21,7 +39,7 @@ Detect the artifact type from the file path basename. Match against these patter
 | `test-plan.md` | test-plan-rules | Test Plan |
 | `epics-and-stories.md` | epics-rules | Epics and Stories |
 
-### Detection Algorithm
+### Path-Based Detection Algorithm
 
 1. Extract the basename from the artifact path (e.g., `docs/planning-artifacts/prd.md` -> `prd.md`)
 2. Match basename against the mapping table above (case-insensitive)
@@ -30,6 +48,7 @@ Detect the artifact type from the file path basename. Match against these patter
 
 ### Edge Cases and Fallback
 
+- **Frontmatter takes priority**: If both frontmatter and filename match, frontmatter wins
 - **Nested directories**: Only the basename matters — `any/nested/path/prd.md` still matches prd-rules
 - **Custom paths**: Files with non-standard names (e.g., `custom-doc.md`) fall back to unknown/unrecognized type
 - **Case sensitivity**: Match is case-insensitive (`PRD.md` and `prd.md` both match prd-rules)
@@ -66,6 +85,72 @@ Verify user personas referenced in requirements match personas defined in the pe
 Verify terminology is used consistently across sections. Cross-reference all sections for contradictions. Flag inconsistencies as WARNING.
 <!-- END SECTION -->
 
+<!-- SECTION: infra-prd-rules -->
+## Infra PRD Validation Rules
+
+Structural quality checks for Infrastructure Product Requirements Documents. This ruleset validates infra PRDs per ADR-022 section 10.16.7 (FR-126).
+
+### Section Presence Check
+
+Verify all 13 required infrastructure PRD sections exist and are non-empty. Flag missing sections as CRITICAL.
+
+Required sections:
+1. Overview & Scope
+2. Goals and Non-Goals
+3. Platform Capabilities
+4. Resource Specifications
+5. Operational SLOs
+6. Security Posture
+7. Environment Strategy & Developer Experience
+8. Dependencies & Provider Constraints
+9. Cost Model
+10. Verification Strategy
+11. Operational Runbooks
+12. Requirements Summary
+13. Open Questions
+
+### IR/OR/SR ID Uniqueness
+
+Verify requirement IDs use the infrastructure ID scheme (IR-###, OR-###, SR-###). Check ID uniqueness within each prefix family — no duplicate IR-001 entries, no duplicate OR-001 entries, no duplicate SR-001 entries. Flag duplicate IDs as WARNING.
+
+### Security Posture Non-Empty
+
+The Security Posture section is mandatory and must be non-empty for all infrastructure PRDs. An empty or placeholder-only Security Posture section is a CRITICAL finding. This section must contain substantive content covering IAM/RBAC, network segmentation, secrets management, or compliance mapping.
+
+### Cost Model Per-Environment Estimates
+
+The Cost Model section must include per-environment cost estimates. At minimum, dev, staging, and prod environments must have cost projections. Flag missing per-environment estimates as WARNING.
+
+### Verification Strategy Policy-as-Code Reference
+
+The Verification Strategy section must reference at least one policy-as-code tool. Recognized tools include: OPA, Rego, Checkov, tfsec, Sentinel, or equivalent. Flag missing policy-as-code references as WARNING.
+
+### Platform Capabilities Format Validation
+
+Each entry in the Platform Capabilities section must follow the format: "Enable {team/service} to {capability} with {SLO}". Entries that do not match this pattern should be flagged as WARNING with a suggestion to reformat.
+<!-- END SECTION -->
+
+<!-- SECTION: platform-prd-rules -->
+## Platform PRD Validation Rules
+
+Platform PRDs represent hybrid projects that combine application and infrastructure concerns. A platform PRD must pass both the `prd-rules` (application) and `infra-prd-rules` (infrastructure) validation rulesets.
+
+### Composite Validation
+
+When validating a platform PRD (detected via `template: 'platform-prd'` in frontmatter):
+1. Run all checks from `prd-rules` — application structural rules apply
+2. Run all checks from `infra-prd-rules` — infrastructure structural rules apply
+3. Merge findings from both rulesets into a single report
+
+### Dual ID Scheme Validation
+
+Platform PRDs use both application and infrastructure requirement ID schemes:
+- Application requirements: FR-### (functional) and NFR-### (non-functional)
+- Infrastructure requirements: IR-### (infrastructure), OR-### (operational), SR-### (security)
+
+Both ID namespaces must be validated for uniqueness within their respective prefix families. No collisions between FR-001 and IR-001 because the prefix disambiguates.
+<!-- END SECTION -->
+
 <!-- SECTION: arch-rules -->
 ## Architecture Validation Rules
 

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`