gaia-framework 1.66.0 → 1.83.2

package/_gaia/dev/skills/figma-integration.md

@@ -0,0 +1,296 @@
+---
+name: figma-integration
+version: '1.0'
+requires_mcp: design-tool
+applicable_agents: [typescript-dev, angular-dev, flutter-dev, java-dev, python-dev, mobile-dev]
+test_scenarios:
+  - scenario: Figma MCP server available and healthy
+    expected: Mode selection (Generate/Import/Skip) presented to user
+  - scenario: Figma MCP server not installed
+    expected: Silent fallback to markdown-only, no error or warning
+  - scenario: Figma MCP server not running
+    expected: Silent fallback to markdown-only, no error or warning
+  - scenario: Figma API token expired
+    expected: Warning displayed, fallback to markdown-only
+  - scenario: Rate limited (429)
+    expected: Single retry after delay, fallback with warning if retry fails
+  - scenario: Timeout exceeding 5 seconds
+    expected: Fallback with warning, continue markdown-only
+  - scenario: Design tool detection via MCP probe
+    expected: Correct adapter selected based on available MCP tool prefix
+  - scenario: Token extraction produces W3C DTCG format
+    expected: design-tokens.json contains $type/$value structure with semantic aliases
+  - scenario: Component spec extraction
+    expected: component-specs.yaml contains typed props, abstract layout, and states
+---
+
+**DesignToolProvider Interface** — abstract interface for design tool integrations. Adapters implement these 5 operations:
+
+| Operation | Description | Returns |
+|-----------|-------------|---------|
+| `detect()` | Probe MCP tools to identify available design tool | Adapter instance or null |
+| `getTokens()` | Extract design tokens from the design file | W3C DTCG JSON (`design-tokens.json`) |
+| `getComponents()` | Extract component specifications | YAML spec (`component-specs.yaml`) |
+| `getFrames()` | Generate UI kit frames across viewports | Frame metadata for UI kit page |
+| `exportAssets()` | Export images and icons at required densities | Asset files in `assets/` directory |
+
+**Adapter Implementations:**
+- **FigmaAdapter** (active) — wraps `figma_*` / `figma/` MCP tools (e.g., `figma/get_file`, `figma/get_styles`, `figma/get_components`). Detected when MCP tools matching prefix `figma` are available.
+- **PenpotAdapter** (planned) — will wrap `penpot_*` MCP tools. Detected via `penpot_` prefix. Not yet implemented.
+- **SketchAdapter** (planned) — will wrap `sketch_*` MCP tools. Detected via `sketch_` prefix. Not yet implemented.
+
+**Selection logic:** probe MCP tool list for known prefixes in order: `figma_` / `figma/` → `penpot_` → `sketch_`. Use the first match. If none found, report "No design tool MCP server detected."
+
+**MCP constraint (FR-140):** operations are read-heavy/write-light. Most interactions read design data (tokens, components, styles). Write operations are limited to frame generation and are clearly documented per section.
+
+<!-- SECTION: detection -->
+## Detection Probe
+
+Detect Figma MCP server availability using a lightweight, read-only probe call.
+This section is consumed by `/gaia-create-ux` at workflow start.
+
+> **Security mandate:** NEVER persist Figma API tokens in any GAIA file — checkpoints, sidecars, logs, or artifacts. MCP auth is handled by the MCP server process; GAIA does not touch tokens.
+
+> **Detection-only mandate:** GAIA MUST never install, configure, or modify the MCP server. Detection is read-only — probe for availability via `figma/get_user_info` or tool listing, nothing more.
+
+### Probe Call
+
+Use `figma/get_user_info` as the detection probe:
+- Read-only, lightweight, validates both connectivity and token validity
+- 5-second hard timeout (NFR-026 compliance)
+- Zero added latency when MCP is not available (silent skip)
+
+### Detection Flow
+
+1. **Attempt probe:** call `figma/get_user_info` with a 5-second hard timeout
+2. **On success:** set `figma_mcp_available = true`, proceed to mode selection
+3. **On failure:** classify the failure and handle per the failure mode table below
+
+### Failure Mode Handling
+
+| Failure | Detection Signal | Behavior |
+|---------|-----------------|----------|
+| **Not installed** (AC5) | Tool not found / tool not available | Silent fallback to markdown-only mode — no error, no warning, no prompt |
+| **Not running** (AC6) | Connection refused / connection error | Silent fallback to markdown-only mode — no error, no warning, no prompt |
+| **Token expired** (AC7) | 401 or 403 response from `figma/get_user_info` | Warn: "Figma token expired — falling back to markdown" then continue markdown-only |
+| **Rate limited** (AC8) | 429 response | Retry once after `Retry-After` header delay (default: 2 seconds). If retry also fails, warn and fallback to markdown-only |
+| **Timeout** (AC9) | No response within 5-second hard timeout | Warn: "Figma MCP did not respond within 5 seconds — falling back to markdown" then continue markdown-only |
+| **Malformed response** | Unexpected or partial data | Treat as unavailable — silent fallback to markdown-only |
+
+### Mode Selection (on success)
+
+When `figma_mcp_available == true`, present the user with:
+
+```
+Figma MCP detected. Select UX design mode:
+  [g] Generate — AI-generated UX with Figma export
+  [i] Import  — Import existing Figma designs into GAIA
+  [s] Skip    — Proceed with markdown-only (ignore Figma)
+```
+
+### Minimum API Scopes
+
+The Figma API token used by the MCP server requires these minimum scopes:
+
+| Scope | Required For | Mode |
+|-------|-------------|------|
+| `files:read` | Reading design files, styles, components | Default (all modes) |
+| `file_content:read` | Reading file content, nodes, images | Default (all modes) |
+| `files:write` | Creating frames, writing to design files | Generate mode only |
+
+Scope enforcement is the MCP server's responsibility — GAIA documents scope expectations only and does not validate or request token scopes.
+
+### Error Sanitization Rules
+
+All error messages from MCP operations MUST follow this safe error format:
+
+```
+Figma MCP error: {status_code} — {generic_description}. Falling back to markdown-only workflow.
+```
+
+**Disallowed content in error messages:** Figma file URLs, file keys, node IDs, design data, access tokens, or any dynamic content from the Figma API response.
+
+| Status Code | Generic Description |
+|-------------|-------------------|
+| 401 | Authentication failed |
+| 403 | Access denied |
+| 404 | Resource not found |
+| 429 | Rate limit exceeded — retry once, then fallback |
+| 500 | Server error |
+
+### Security Boundary
+
+- The Figma API token lives exclusively in the MCP server configuration (ADR-024)
+- GAIA files must NEVER contain or log Figma tokens, API keys, or credentials
+- Detection probe interacts through MCP tool abstraction only — no direct HTTP calls
+
+### Traceability
+
+- FR-132: Figma MCP detection probe requirement
+- FR-143: Graceful MCP failure handling
+- NFR-026: MCP detection latency < 5 seconds
+- ADR-024: Figma MCP integration via shared skill
+
+<!-- SECTION: tokens -->
+## Design Token Extraction
+
+> **Security mandate:** MCP auth is handled by the MCP server — NEVER persist or reference Figma API tokens in extraction outputs, logs, or GAIA files.
+
+Extract design tokens from the connected design tool and output in W3C DTCG format.
+
+### Extraction Steps
+
+1. **Fetch styles** — call `figma/get_styles` to retrieve all published styles (colors, typography, effects, grids)
+2. **Map to W3C DTCG** — transform each style into the W3C Design Tokens Community Group draft format:
+   ```json
+   {
+     "color": {
+       "primary": { "$type": "color", "$value": "#3B82F6", "$description": "Brand primary" }
+     },
+     "spacing": {
+       "sm": { "$type": "dimension", "$value": "8px" }
+     },
+     "typography": {
+       "heading-1": {
+         "$type": "typography",
+         "$value": { "fontFamily": "Inter", "fontSize": "32px", "fontWeight": 700, "lineHeight": 1.2 }
+       }
+     }
+   }
+   ```
+3. **Include semantic aliases** — map raw tokens to semantic names (e.g., `color.surface.primary` → `color.blue.500`)
+4. **Add composite tokens** — typography composites, shadow composites, border-radius scales
+5. **Write output** — save to `{planning_artifacts}/design-system/design-tokens.json` with `"schema_version": "1.0"`
+
+<!-- SECTION: components -->
+## Component Spec Extraction
+
+> **Security mandate:** MCP auth is handled by the MCP server — NEVER include Figma API tokens in component specs, logs, or any GAIA output files.
+
+Extract component specifications into a tech-agnostic intermediate format.
+
+### Extraction Steps
+
+1. **Fetch components** — call `figma/get_components` to list all published components and variants
+2. **For each component**, extract:
+   - **name** — component name (PascalCase)
+   - **props** — typed properties: `{ name: string, type: "string"|"number"|"boolean"|"enum", values?: string[] }`
+   - **layout** — abstract layout type: `row | column | stack | grid` with spacing via token references (`{spacing.sm}`)
+   - **states** — `[default, hover, active, disabled, focus]` with visual diff per state
+   - **children** — nested component references with slot definitions
+   - **variants** — named variants with their property overrides
+   - **responsive** — breakpoint behavior at 375px, 768px, 1280px
+   - **a11y** — role, aria-label pattern, description, keyboard interaction
+3. **Write output** — save to `{planning_artifacts}/design-system/component-specs.yaml` with `schema_version: "1.0"`
+
+### Output Schema
+
+```yaml
+schema_version: "1.0"
+components:
+  - name: Button
+    props:
+      - { name: label, type: string }
+      - { name: variant, type: enum, values: [primary, secondary, ghost] }
+      - { name: disabled, type: boolean }
+    layout: { type: row, gap: "{spacing.sm}" }
+    states: [default, hover, active, disabled, focus]
+    a11y: { role: button, label: "{props.label}" }
+```
+
+<!-- SECTION: frames -->
+## Frame Generation
+
+> **Security mandate:** MCP auth is handled by the MCP server — NEVER persist Figma API tokens in frame metadata, logs, or any GAIA output files.
+
+Create UI kit frames in the design tool across standard viewports.
+
+### Generation Steps
+
+1. **Create UI Kit page** — create a dedicated page named "UI Kit — Generated" in the design file
+2. **For each screen** defined in the UX design:
+   - Create 3 viewport frames: mobile (375px), tablet (768px), desktop (1280px)
+   - Apply auto-layout with responsive constraints from component specs
+   - Place components using the extracted component specs and token values
+3. **Add prototype flows** — link frames with interaction flows matching the UX navigation spec
+4. **Label frames** — use naming convention: `{ScreenName}/{Viewport}` (e.g., `Dashboard/Desktop`)
+
+### Output
+
+Frame metadata logged for verification. No file output — frames are created directly in the design tool via MCP calls (`figma/create_frame`, `figma/create_component_instance`).
+
+<!-- SECTION: assets -->
+## Asset Export
+
+> **Security mandate:** MCP auth is handled by the MCP server — NEVER include Figma API tokens in asset manifests, export logs, or any GAIA output files.
+
+Export raster and vector assets from the design tool at required densities.
+
+### Export Steps
+
+1. **Identify exportable nodes** — scan the design file for nodes marked as exportable (icons, images, illustrations)
+2. **Export icons** as SVG — call `figma/get_images` with `format: svg` for all icon nodes
+3. **Export images** as PNG at 3 densities — call `figma/get_images` with `format: png` and `scale: 1`, `scale: 2`, `scale: 3` for image nodes
+4. **Organize output** into directory structure:
+   ```
+   {planning_artifacts}/design-system/assets/
+   ├── icons/          # SVG icons
+   │   ├── icon-name.svg
+   ├── images/         # PNG images at 1x/2x/3x
+   │   ├── image-name@1x.png
+   │   ├── image-name@2x.png
+   │   └── image-name@3x.png
+   ```
+5. **Generate asset manifest** — list all exported assets with dimensions and file sizes
+
+<!-- SECTION: export -->
+## Per-Stack Token Resolution
+
+> **Security mandate:** MCP auth is handled by the MCP server — NEVER embed Figma API tokens in generated token files, stack outputs, or any GAIA output files.
+
+Maps abstract design tokens to framework-specific implementations. Each dev agent uses this table to generate native code from `design-tokens.json`.
+
+| Agent | Stack | Token Format | Example |
+|-------|-------|-------------|---------|
+| Cleo | TypeScript/React | CSS custom properties | `--color-primary: #3B82F6;` in `:root {}` |
+| Lena | Angular | SCSS variables + CSS custom properties | `$color-primary: #3B82F6;` in `_tokens.scss` |
+| Freya | Flutter/Dart | ThemeData extensions | `ThemeData(primaryColor: Color(0xFF3B82F6))` |
+| Hugo | Java/Spring | Spring properties + Java constants | `design.color.primary=#3B82F6` in `application.properties` |
+| Ravi | Python | Python dict constants | `TOKENS = {"color": {"primary": "#3B82F6"}}` in `design_tokens.py` |
+| Talia | Mobile (RN/Swift/Compose) | RN StyleSheet / Swift extensions / Compose theme | `StyleSheet.create({primary: '#3B82F6'})` or `extension UIColor { static let primary = UIColor(hex: "3B82F6") }` or `val Primary = Color(0xFF3B82F6)` |
+
+### Resolution Process
+
+1. Read `design-tokens.json` (W3C DTCG format) from `{planning_artifacts}/design-system/`
+2. Read `component-specs.yaml` from the same directory for component definitions and widget hints
+3. Identify the active dev agent's stack from the agent persona
+4. For each token, generate the stack-native representation using the table above
+5. For each component, use the `widget_hints` field to guide framework-specific widget/component tree generation
+6. Output token files to the project's design system directory (stack-specific path)
+
+### Token Path Resolution Rules
+
+Token paths use `{group.token}` syntax. The resolution pattern per stack:
+
+| Stack | Pattern | Example Path | Resolved Output |
+|-------|---------|-------------|-----------------|
+| TypeScript/React | `--{group}-{token}` | `{color.blue-500}` | `var(--color-blue-500)` |
+| Angular | `${group}-{token}` | `{spacing.4}` | `$spacing-4` |
+| Flutter/Dart | `AppTokens.{group}.{token}` | `{typography.body}` | `AppTokens.typography.body` |
+| Java/Spring | `design.{group}.{token}` | `{color.interactive-primary}` | `design.color.interactive-primary` |
+| Python | `TOKENS['{group}']['{token}']` | `{shadow.md}` | `TOKENS['shadow']['md']` |
+| Mobile (RN) | `tokens.{group}.{token}` | `{borderRadius.md}` | `tokens.borderRadius.md` |
+| Mobile (Swift) | `DesignTokens.{group}.{token}` | `{color.blue-500}` | `DesignTokens.color.blue500` |
+| Mobile (Compose) | `AppTheme.{group}.{token}` | `{spacing.2}` | `AppTheme.spacing.s2` |
+
+### Semantic Alias Resolution
+
+Semantic tokens reference primitives via `{group.token}` syntax in their `$value` field. When generating stack-specific code, resolve the alias chain to produce the final value. Example:
+
+```
+"interactive-primary": { "$type": "color", "$value": "{color.blue-500}" }
+→ resolves to → #3B82F6
+→ CSS: --color-interactive-primary: #3B82F6;
+→ SCSS: $color-interactive-primary: #3B82F6;
+→ Dart: static const interactivePrimary = Color(0xFF3B82F6);
+```

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

@@ -3,6 +3,7 @@
 > 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.
+> Non-REST protocols: E11-S17 — GraphQL and gRPC endpoint detection and security gap scanning.
 
 ## Objective
 
@@ -51,6 +52,89 @@ Apply framework-specific patterns based on {tech_stack}:
 
 If no API endpoints are detected, output a summary note and zero gap entries for the application phase.
 
+## Phase 1b: GraphQL Endpoint Discovery
+
+Catalog all GraphQL endpoints. For each endpoint, record: operation type (query/mutation/subscription), resolver function, authentication directives, authorization checks.
+
+### Schema-First Detection Patterns
+
+- `.graphql` and `.gql` schema files
+- `type Query { ... }` and `type Mutation { ... }` blocks in schema files
+- `typeDefs` variable definitions in JS/TS files (template literals with SDL)
+
+### Code-First Detection Patterns
+
+- `@Resolver()` decorators (NestJS, TypeGraphQL)
+- `@Query()` and `@Mutation()` decorators
+- `resolvers` objects exported from modules
+- Python class-based resolvers (Strawberry `@strawberry.type`, Ariadne `@query_type.field`)
+- Go resolver structs (gqlgen `resolver.go` files)
+
+### GraphQL Framework Variants
+
+Apply framework-specific patterns based on detected GraphQL library:
+
+| Framework | Language | Detection Pattern |
+|---|---|---|
+| Apollo Server | Node/TS | `ApolloServer`, `@apollo/server`, Apollo plugins |
+| GraphQL Yoga | Node/TS | `createYoga`, `@graphql-yoga/node` |
+| Mercurius | Node/TS (Fastify) | `mercurius`, `app.graphql` |
+| Strawberry | Python | `strawberry.Schema`, `@strawberry.type` |
+| gqlgen | Go | `gqlgen.yml`, `generated.go`, resolver structs |
+| Ariadne | Python | `ariadne`, `make_executable_schema` |
+| NestJS GraphQL | Node/TS | `@nestjs/graphql`, `@Resolver()`, `@Query()`, `@Mutation()` |
+
+### GraphQL Middleware Chain Detection
+
+- `graphql-shield` rule trees (`const permissions = shield({ ... })`)
+- `@UseGuards(AuthGuard)` decorators (NestJS)
+- Apollo Server plugins (`ApolloServerPlugin` implementing `requestDidStart`)
+- Yoga plugins (`useAuth`, custom `envelop` plugins)
+- Custom context resolvers setting `context.user` from auth headers
+
+### Graceful Exit — No GraphQL Endpoints
+
+If no GraphQL schema files, resolver definitions, or GraphQL framework imports are detected, skip Phase 1b and Phase 2b entirely. Output a summary note and zero gap entries for GraphQL.
+
+## Phase 1c: gRPC Endpoint Discovery
+
+Catalog all gRPC endpoints. For each endpoint, record: service name, RPC method name, request/response message types, streaming type (unary/server/client/bidirectional), interceptor chain.
+
+### Proto Service Parsing
+
+- `.proto` files with `service` blocks defining `rpc` methods
+- `stream` annotations on request or response types (server streaming, client streaming, bidirectional streaming)
+- `package` declarations for service namespace
+
+### Server Interceptor Detection
+
+| Language | Interceptor Pattern |
+|---|---|
+| Java | `ServerInterceptor` interface, `@GrpcService` (Spring gRPC), interceptor registry |
+| Go | `grpc.UnaryInterceptor()`, `grpc.StreamInterceptor()`, `grpc.ChainUnaryInterceptor()` |
+| Python | `grpc.server_interceptor`, `intercept_service()` |
+| Node/TS | `addService()` calls, `@GrpcMethod` decorators (NestJS), `grpc-js` server options |
+
+### gRPC Middleware Chain Detection
+
+- Interceptor chains in server setup (ordered middleware)
+- `@GrpcMethod` decorators with guard annotations (NestJS)
+- Metadata extractors for authentication tokens
+- Health check service registration (`grpc.health.v1`)
+
+### Graceful Exit — No gRPC Endpoints
+
+If no `.proto` files, gRPC server setup, or gRPC framework imports are detected, skip Phase 1c and Phase 2c entirely. Output a summary note and zero gap entries for gRPC.
+
+## Phase 1d: Mixed-Protocol Detection
+
+A single codebase may expose REST + GraphQL + gRPC endpoints simultaneously. When multiple protocols are detected:
+
+1. Scan all three protocols independently
+2. Identify shared authentication middleware (e.g., a JWT validator used by both Express routes and Apollo context)
+3. Do not double-count shared middleware as separate gaps — if auth middleware covers both REST and GraphQL, count it once
+4. Note in findings when multiple protocols share infrastructure
+
 ## Phase 2: Security Gap Detection — Application Rules
 
 ### 1. Missing Authentication Middleware (AC3a)
@@ -82,6 +166,99 @@ Sensitive data exposure is `high` severity.
 
 Detect POST/PUT/PATCH/DELETE endpoints that accept a request body but have no input validation. Missing input validation is `high` severity.
 
+## Phase 2b: GraphQL Security Gap Detection
+
+### 1. Queries/Mutations Missing Auth Directives
+
+Detect GraphQL operations missing authentication. Look for:
+- Resolvers without `@auth`, `@authenticated`, `@HasPermission`, or `@UseGuards(AuthGuard)` directives
+- Schema types without `@auth` directive when other types have it (inconsistent protection)
+- Mutation resolvers with no authorization checks are `critical` severity
+- Query resolvers returning non-public data without auth are `high` severity
+
+### 2. Introspection Enabled in Production
+
+Detect GraphQL introspection configuration that may leak schema in production:
+- `introspection: true` in Apollo Server config without `NODE_ENV` conditional
+- Missing introspection disable in production configuration
+- Yoga/Mercurius default introspection without explicit disable
+
+Introspection in production is `medium` severity.
+
+### 3. Mutations Without Authorization Checks
+
+Detect mutation resolvers that lack authorization logic:
+- Mutation handlers with no permission checks, guard decorators, or authorization middleware
+- `graphql-shield` rules that allow mutations without role checks
+- NestJS mutations without `@UseGuards()` when other mutations have guards
+
+Missing mutation authorization is `critical` severity.
+
+### 4. Field-Level Authorization Gaps
+
+Detect sensitive fields exposed without field-level auth controls:
+- Fields named `email`, `password`, `ssn`, `token`, `secret`, `creditCard` without `@Authorized` or field-level resolvers
+- Resolver types exposing sensitive nested objects without per-field permission checks
+- User types exposing admin-only fields to all authenticated users
+
+Field-level authorization gaps are `high` severity.
+
+### 5. GraphQL Federation and Schema Stitching
+
+When Apollo Federation or schema stitching is detected:
+- Note gateway-level auth that may mask per-service gaps
+- Flag subgraph services that rely solely on gateway auth without their own validation
+- Detect `@external` fields without authorization in the owning subgraph
+
+Federation auth gaps are `medium` severity with a note about gateway-level coverage.
+
+## Phase 2c: gRPC Security Gap Detection
+
+### 1. Services Missing Auth Interceptors
+
+Detect gRPC server setup without authentication interceptors:
+- Server initialization without `AuthInterceptor` or equivalent in the interceptor chain
+- Services registered via `addService` with no auth middleware applied
+- Spring gRPC services without `@GrpcService` security configuration
+
+Missing auth interceptor is `critical` severity.
+
+### 2. Unary RPCs Without Authorization Metadata
+
+Detect unary RPC methods that do not validate authorization metadata:
+- `rpc` method handlers that do not extract or validate `metadata` authorization headers
+- Handler functions that skip token/credential validation from gRPC metadata
+- Methods that do not check caller identity or roles from request context
+
+Missing unary authorization is `high` severity.
+
+### 3. Streaming RPCs Without Per-Message Auth
+
+Detect bidirectional and server streaming RPCs without per-message authentication:
+- Stream handlers that authenticate only at connection start but not per-message
+- Bidirectional streams without per-message auth validation
+- Server streaming RPCs that do not re-validate authorization on long-lived connections
+
+Missing stream auth is `high` severity.
+
+### 4. TLS Configuration Gaps
+
+Detect insecure gRPC transport configuration:
+- `grpc.insecure_port` usage in non-development configuration
+- `ServerCredentials.createInsecure()` in production server setup
+- Missing TLS certificate configuration in production gRPC servers
+- Plaintext gRPC channels in production client configuration
+
+Insecure TLS is `critical` severity.
+
+### 5. gRPC Reflection Enabled in Production
+
+Detect gRPC reflection service that may expose service definitions:
+- `grpc.reflection.v1alpha` or `grpc.reflection.v1` service registered without environment guard
+- Reflection service enabled unconditionally (similar risk to GraphQL introspection)
+
+Reflection in production is `medium` severity.
+
 ## Phase 3: False-Positive Mitigation — Inherited Auth
 
 Before flagging an endpoint as "missing authentication middleware," trace the middleware chain upward:
@@ -106,6 +283,18 @@ Before flagging an endpoint as "missing authentication middleware," trace the mi
 - `r.Use(JWTAuth())` — app-level
 - `group := r.Group("/api"); group.Use(AuthMiddleware())` — group-level
 
+#### GraphQL Inherited Auth
+- Apollo Server `context` function that validates JWT and sets `context.user` — app-level
+- `graphql-shield` rule tree applied via `applyMiddleware` — schema-level
+- NestJS `@UseGuards(AuthGuard)` on resolver class — class-level
+- Apollo Federation gateway-level auth that validates before routing to subgraphs — gateway-level
+
+#### gRPC Inherited Auth
+- Global auth interceptor registered via `grpc.UnaryInterceptor(authInterceptor)` — server-level
+- `ServerInterceptor` added to server builder interceptor chain — server-level
+- Per-service interceptor applied at `addService` — service-level
+- TLS mutual authentication (mTLS) at transport level — transport-level
+
 ## Phase 4: Infrastructure Security Patterns (E12-S6)
 
 **Apply ONLY when {project_type} is `infrastructure` or `platform`.**
@@ -180,11 +369,50 @@ gap:
   evidence:
     file: "relative/path/to/file"
     line: 42
+    protocol: "rest"
   recommendation: "Actionable fix — add middleware, validate input, filter response"
   verified_by: "machine-detected"
   confidence: "{high|medium|low}"
 ```
 
+**Protocol field:** Every gap entry MUST include a `protocol` field in the evidence section indicating which API protocol the finding applies to: `rest`, `graphql`, or `grpc`. This enables downstream consumers to filter and route findings by protocol.
+
+#### GraphQL Gap Example
+
+```yaml
+gap:
+  id: "GAP-SECURITY-015"
+  category: "security-endpoint"
+  severity: "critical"
+  title: "Mutation resolver missing authorization checks"
+  description: "createUser mutation has no @auth directive or guard. Any authenticated user can create accounts."
+  evidence:
+    file: "src/graphql/resolvers/user.resolver.ts"
+    line: 42
+    protocol: "graphql"
+  recommendation: "Add @UseGuards(AuthGuard, RolesGuard) or @auth directive to the createUser mutation."
+  verified_by: "machine-detected"
+  confidence: "high"
+```
+
+#### gRPC Gap Example
+
+```yaml
+gap:
+  id: "GAP-SECURITY-022"
+  category: "security-endpoint"
+  severity: "critical"
+  title: "gRPC server missing auth interceptor in production config"
+  description: "Server setup uses grpc.insecure_port without TLS. No auth interceptor in interceptor chain."
+  evidence:
+    file: "cmd/server/main.go"
+    line: 58
+    protocol: "grpc"
+  recommendation: "Add TLS credentials and an auth interceptor to the gRPC server configuration."
+  verified_by: "machine-detected"
+  confidence: "high"
+```
+
 ### Confidence Classification
 
 - **high** — exact pattern match (e.g., no auth decorator/annotation on a `@PostMapping` handler)

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

@@ -1,7 +1,7 @@
 # Gap Entry Schema
 
-> **Version:** 1.1.0
-> **Story:** E11-S1, E12-S5
+> **Version:** 1.2.0
+> **Story:** E11-S1, E12-S5, E11-S18
 > **Traces to:** FR-111, FR-123, US-38, ADR-021, ADR-022
 >
 > Standardized output schema for brownfield scan subagents (E11).
@@ -22,6 +22,7 @@ description: "<string>"
 evidence:
   file: "<relative-path>"
   line: <number-or-range>
+  protocol: "<string>"           # Optional
 recommendation: "<string>"
 verified_by: "<agent-id>"
 confidence: "<enum>"
@@ -36,7 +37,7 @@ confidence: "<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) |
+| `evidence` | object | yes | Source code evidence with required `file` and `line` sub-fields, plus optional `protocol` sub-field (see Evidence Object) |
 | `recommendation` | string | yes | Actionable fix or remediation guidance |
 | `verified_by` | string | yes | ID of the scan agent that produced this finding (e.g., `dead-code-analyzer`, `config-scanner`) |
 | `confidence` | enum | yes | Agent's confidence in the finding accuracy (see Confidence Enum) |
@@ -95,6 +96,7 @@ The `evidence` field is a composite object grouping source location data:
 evidence:
   file: "src/services/auth.ts"    # Relative path from project root (non-empty string)
   line: 42                        # Single line number
+  protocol: "rest"                # Optional. Protocol type
 ```
 
 Or with a line range:
@@ -105,10 +107,19 @@ evidence:
   line: "15-28"                   # Line range (start-end)
 ```
 
+Or without the optional protocol field (backward compatible):
+
+```yaml
+evidence:
+  file: "src/utils/helper.ts"
+  line: 10
+```
+
 | Sub-field | Type | Required | Constraints |
 |-----------|------|----------|-------------|
 | `file` | string | yes | Relative path from project root. Must be non-empty. |
 | `line` | number or string | yes | Single line number (integer) or range as `"start-end"` string |
+| `protocol` | string | no | Optional. One of `rest`, `graphql`, `grpc`, `websocket`, or any custom string. Omit if not applicable. When present, must be a non-empty string. |
 
 ## ID Format
 
@@ -138,10 +149,17 @@ All fields listed in the Field Reference are **required** — a gap entry with a
 - `evidence.line` must be a positive integer or a range string matching `^\d+-\d+$`
 - `title` should not exceed 80 characters
 - `verified_by` must be a non-empty string identifying the scan agent
+- `evidence.protocol` when present, must be a non-empty string
 
 ### Required vs Optional
 
-All 9 fields (`id`, `category`, `severity`, `title`, `description`, `evidence`, `recommendation`, `verified_by`, `confidence`) are **required**. There are no optional fields in the base schema.
+All 9 top-level fields (`id`, `category`, `severity`, `title`, `description`, `evidence`, `recommendation`, `verified_by`, `confidence`) are **required**. There are no optional top-level fields in the base schema.
+
+The `evidence` object contains one optional sub-field: `protocol`. This is the first optional sub-field in the schema. Existing gap entries that omit `protocol` remain fully valid.
+
+### Optional Field Validation
+
+The `protocol` sub-field of the `evidence` object is not enum-validated. It accepts any non-empty string when present. Recommended canonical values are `rest`, `graphql`, `grpc`, and `websocket`, but custom strings (e.g., `mqtt`, `soap`, `amqp`) are also accepted without schema changes. When `protocol` is omitted entirely, the gap entry remains valid (backward compatible). When present, an empty string is invalid.
 
 ## Budget Control
 
@@ -174,6 +192,23 @@ verified_by: "config-scanner"
 confidence: "high"
 ```
 
+### Application Category Example with Protocol
+
+```yaml
+id: "GAP-security-endpoint-001"
+category: "security-endpoint"
+severity: "high"
+title: "Unprotected admin route exposes user management API"
+description: "The /api/admin/users endpoint has no authentication middleware applied."
+evidence:
+  file: "src/routes/admin.ts"
+  line: 15
+  protocol: "rest"
+recommendation: "Add authentication middleware to all /api/admin/* routes."
+verified_by: "security-scanner"
+confidence: "high"
+```
+
 ### Infrastructure Category Examples
 
 ```yaml