gaia-framework 1.66.0 → 1.87.0

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

package/_gaia/lifecycle/templates/story-template.md

@@ -12,11 +12,20 @@ points: "{story_points}"
 risk: "{high/medium/low}"
 sprint_id: null
 priority_flag: null
+origin: null
+origin_ref: null
 depends_on: []
 blocks: []
 traces_to: []
 date: "{creation_date}"
 author: "{agent_name}"
+# Optional: Figma design metadata — enables dev agents to extract design tokens and component specs via MCP.
+# Omit this block entirely if the story does not reference Figma designs.
+# figma:
+#   file_key: "{figma_file_key}"       # Figma file identifier (from URL)
+#   pages: ["{page_name}"]             # List of page names to extract from
+#   node_ids: ["{node_id}"]            # List of specific Figma node IDs
+#   design_version: null               # Populated by dev agent after first consumption (lastModified hash)
 ---
 
 # Story: {story_title}
@@ -116,4 +125,23 @@ As a {role}, I want to {action}, so that {benefit}.
 
 ## Definition of Done
 
-- [ ] Define all the Definition of Done
+### Acceptance
+
+- [ ] All acceptance criteria verified and checked off
+- [ ] All subtasks marked complete
+
+### Testing
+
+- [ ] All tests pass (unit, integration, e2e as applicable)
+- [ ] No linting or formatting errors
+
+### Code Quality & CI
+
+- [ ] Code compiles / builds without errors
+- [ ] Code follows project conventions
+- [ ] No hardcoded secrets or credentials
+- [ ] PR merged to staging with all CI checks passing
+
+### Documentation
+
+- [ ] Documentation updated (if applicable)

package/_gaia/lifecycle/workflows/2-planning/create-ux-design/instructions.xml

@@ -32,12 +32,105 @@
   <action>Plan keyboard navigation, screen reader support</action>
   <action>Define color contrast and text sizing standards</action>
 </step>
-<step n="7" title="Generate Output">
+<step n="7" title="Figma MCP Detection and Mode Selection">
+  <action>Probe for available Figma MCP server. Load figma-integration.md detection section JIT to determine if a design tool adapter is available.</action>
+  <action if="figma_mcp_available">Present mode selection to user: [Generate] Create Figma frames alongside ux-design.md | [Import] Import existing Figma designs (read-only) | [Skip] Text-only UX spec, no Figma integration</action>
+  <action if="not figma_mcp_available">Skip Figma integration — proceed with text-only UX design output. Log: "No Figma MCP server detected. Generating markdown-only ux-design.md."</action>
+</step>
+<step n="8" title="Generate Mode — UI Kit Page Creation" if="figma_mcp_available AND user_selected_generate">
+  <critical>
+    <mandate>Generate mode is the ONLY mode that performs write operations to Figma (FR-140). All other modes are read-only. Write operations: create pages, create frames, create component instances. Minimum required Figma API scopes: files:read + file_content:read + files:write.</mandate>
+  </critical>
+  <action>Load figma-integration.md frames section JIT from _gaia/dev/skills/figma-integration.md</action>
+  <action>Create a UI Kit page named "UI Kit — Generated" in the Figma design file via MCP</action>
+  <action>Extract design tokens from {planning_artifacts}/design-system/design-tokens.json (W3C DTCG format)</action>
+  <action>Create color styles with semantic aliases from token definitions (e.g., color.surface.primary, color.text.primary)</action>
+  <action>Create typography styles from composite token specs (heading-1, heading-2, body, caption)</action>
+  <action>Create spacing grid tokens and base components with state variants (default, hover, active, disabled, focus)</action>
+  <action>Error handling: on HTTP 429 rate limit, perform a single retry after backoff. If 429 persists, graceful fallback to markdown-only flow — log warning and skip remaining Figma operations.</action>
+</step>
+<step n="9" title="Generate Mode — Per-Screen Frame Generation" if="figma_mcp_available AND user_selected_generate">
+  <action>Parse PRD user journeys to determine screens needing frames</action>
+  <action>For each screen, generate frames at 6 viewports: 280px (foldable inner, FR-174), 375px (mobile), 600px (foldable outer, FR-174), 768px (tablet portrait), 1024px (tablet landscape, FR-174), 1280px (desktop)</action>
+  <action>Compose frames using UI Kit components from the previous step — apply auto-layout with responsive constraints from component specs</action>
+  <action>Label frames using naming convention: {ScreenName}/{Viewport} (e.g., Dashboard/Desktop, Login/Mobile)</action>
+  <action>Collect all generated Figma node IDs for downstream recording in ux-design.md</action>
+</step>
+<step n="10" title="Generate Mode — Prototype Flow Setup" if="figma_mcp_available AND user_selected_generate">
+  <action>Map PRD user journey steps to the generated screen frames</action>
+  <action>Create prototype flow connections between frames via Figma MCP, linking screens in the order defined by each user journey</action>
+  <action>Validate flow completeness: every user journey step must map to a generated frame. Flag any unmapped journey steps as warnings.</action>
+</step>
+<step n="11" title="Generate Mode — Asset Export Configuration" if="figma_mcp_available AND user_selected_generate">
+  <action>Configure PNG export at 1x, 2x, 3x densities for raster assets (images, illustrations)</action>
+  <action>Configure SVG export for icon components</action>
+  <action>Generate platform-specific asset catalogs per FR-175: iOS .xcassets catalog structure with Contents.json manifests, Android drawable-mdpi/drawable-hdpi/drawable-xhdpi/drawable-xxhdpi/drawable-xxxhdpi directories</action>
+  <action>Write export configuration and asset manifest to {planning_artifacts}/design-system/assets/ directory</action>
+  <action>Check {project-path}/.figma-cache/ for cached responses (1h TTL) before making MCP read calls — use cached data if fresh, fetch and cache if stale or missing</action>
+</step>
+<step n="12" title="Generate Mode — Record Figma Node IDs and Enhance ux-design.md" if="figma_mcp_available AND user_selected_generate">
+  <action>Build Screen-to-Frame mapping table from all generated Figma node IDs: columns Screen Name | Viewport | Figma Node ID | Page</action>
+  <action>Add figma: YAML frontmatter block to ux-design.md containing: file_key, pages array with node IDs for each generated page, and last_synced ISO 8601 timestamp</action>
+  <action>Add Design Tokens reference section linking to {planning_artifacts}/design-system/design-tokens.json with token category summary</action>
+  <action>Add Component Inventory section listing all generated UI Kit components with their Figma node IDs, variant counts, and state definitions</action>
+  <action>Add Screen-to-Frame mapping table with all generated frames across all viewports</action>
+  <action>Ensure backward compatibility: existing text-only ux-design.md content is preserved. Figma sections are additive — they appear after the standard UX design sections.</action>
+</step>
+<step n="13" title="Import Mode — File Key Entry and Validation" if="figma_mcp_available AND user_selected_import">
+  <critical>
+    <mandate>Import mode is strictly READ-ONLY. Only get_file, get_file_nodes, and get_image MCP calls are permitted. Zero write operations to Figma. Minimum required Figma API scopes: files:read + file_content:read.</mandate>
+  </critical>
+  <action>JIT-load figma-integration:import-detection section from _gaia/dev/skills/figma-integration.md</action>
+  <ask>Enter the Figma file URL (e.g., https://www.figma.com/file/abc123/Design-Name) or raw file key:</ask>
+  <action>Parse input: extract file key from URL format, or accept raw key directly</action>
+  <action>Validate key via lightweight figma/get_file MCP call with depth=1 (metadata only)</action>
+  <action>Handle errors: invalid key format (client-side rejection), 404 not found, 403 permission denied, 429 rate limited (single retry after 1s delay), 5-second timeout (abort gracefully per E13-S1)</action>
+</step>
+<step n="14" title="Import Mode — Page and Frame Discovery" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-discovery section</action>
+  <action>Call figma/get_file with full depth to retrieve the complete document tree</action>
+  <action>Parse response: extract pages (top-level CANVAS nodes) and frames (FRAME nodes within each page)</action>
+  <action>Build Page → Frames hierarchy with metadata (name, nodeId, absoluteBoundingBox dimensions)</action>
+  <action>Classify frames by viewport width: mobile (≤480px), tablet (481–1024px), desktop (>1024px)</action>
+  <action>Cache response in {project-path}/.figma-cache/ with 1-hour TTL per ADR-024</action>
+  <action>Handle partial access: if some pages/frames are inaccessible, continue with warnings and proceed with accessible content</action>
+</step>
+<step n="15" title="Import Mode — Design Token Extraction" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-tokens section</action>
+  <action>Extract color styles from file's styles and document nodes, resolving fill/stroke references to RGBA values</action>
+  <action>Extract typography styles: font family, size, weight, line height, letter spacing</action>
+  <action>Extract effect styles: drop-shadow and inner-shadow parameters</action>
+  <action>Extract spacing values from auto-layout frames: itemSpacing, paddingLeft/Right/Top/Bottom</action>
+  <action>Map all extracted tokens to W3C DTCG format with semantic alias support (e.g., Primary/500 → color.primary.500)</action>
+  <action>Write design-tokens.json to {planning_artifacts}/design-system/ with schema_version field</action>
+</step>
+<step n="16" title="Import Mode — Screen Inventory" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-screens section</action>
+  <action>Group frames by page from the discovered hierarchy</action>
+  <action>Build per-frame metadata: name, nodeId, width, height, viewport classification</action>
+  <action>Extract component instances used in each frame — map to component-specs.yaml format (name, props, layout type)</action>
+  <action>Generate structured screen-to-frame mapping with tracked nodeIds for downstream dev agent consumption (E13-S5)</action>
+  <action>Write component-specs.yaml to {planning_artifacts}/design-system/</action>
+</step>
+<step n="17" title="Import Mode — Generate ux-design.md Content" if="figma_mcp_available AND user_selected_import">
+  <action>JIT-load figma-integration:import-generate section</action>
+  <action>Prepare figma: YAML frontmatter block containing: file_key, pages array, node_ids array, imported_at ISO 8601 timestamp, import_mode: true</action>
+  <action>Prepare Design Tokens section with token path references (e.g., {color.primary}, {spacing.4})</action>
+  <action>Prepare Component Inventory section listing all components discovered from frame extraction with props and variants</action>
+  <action>Prepare Screen Descriptions section with per-screen: frame name, node ID, viewport classification, component list, layout description</action>
+  <action>Verify read-only guarantee: audit all MCP calls made during steps 13-17 — confirm only get_file, get_file_nodes, and get_image were used. Zero write operations. Abort and report if any write operation is detected.</action>
+</step>
+<step n="18" title="Generate Output">
   <template-output file="{planning_artifacts}/ux-design.md">
-    Generate UX design document with: personas, information architecture, wireframe descriptions, interaction patterns, component specifications, accessibility plan, and FR-to-Screen Mapping table (FR ID | Screen/Page | Wireframe Section).
+    Generate UX design document with: personas, information architecture, wireframe descriptions, interaction patterns, component specifications, accessibility plan, FR-to-Screen Mapping table (FR ID | Screen/Page | Wireframe Section). If Generate mode was active: include figma: frontmatter block, Design Tokens section, Component Inventory with Figma node IDs, and Screen-to-Frame mapping table. If Import mode was active: include figma: frontmatter block (file_key, pages, node_ids, imported_at, import_mode: true), Design Tokens section with token references, Component Inventory, and Screen Descriptions.
   </template-output>
 </step>
-<step n="8" title="Optional: Accessibility Review">
+<step n="19" title="FR-140 Compliance Check" if="figma_mcp_available AND user_selected_generate">
+  <action>Audit all MCP calls executed during Generate mode: classify each as READ (get_file, get_styles, get_components, get_images, get_frames) or WRITE (create_frame, create_component_instance, create_page)</action>
+  <action>Verify FR-140 constraint: write operations only occurred during Generate mode steps (8–12). Import mode and Skip mode must have zero write calls.</action>
+  <action>Document minimum required Figma API scopes: files:read + file_content:read (default for all modes), files:write (Generate mode only)</action>
+</step>
+<step n="20" title="Optional: Accessibility Review">
   <ask>Would you like to review the UX design for WCAG 2.1 accessibility compliance? This spawns a subagent in a separate context. Recommended for user-facing applications. (yes / skip)</ask>
   <action>If yes: spawn a subagent using the Agent tool: "Load {project-root}/_gaia/core/tasks/review-accessibility.xml. Read its entire contents. Target: {planning_artifacts}/ux-design.md. Follow the flow steps EXACTLY. Generate accessibility findings report."</action>
   <action>If skip: accessibility review can be run anytime later with /gaia-review-a11y</action>

package/_gaia/lifecycle/workflows/4-implementation/code-review/instructions.xml

@@ -25,6 +25,16 @@
   </action>
   <action>Include an "Architecture Conformance" section in findings with PASS/FAIL per check</action>
 </step>
+<step n="3c" title="Design Fidelity Check">
+  <action>Read story file YAML frontmatter — check if a `figma:` block exists</action>
+  <action if="story_has_figma_block">Load the `figma-integration:fidelity` section JIT from `_gaia/dev/skills/figma-integration.md`</action>
+  <action if="story_has_figma_block">Run the fidelity comparison: extract token references from changed code files, compare against `{planning_artifacts}/design-system/design-tokens.json`, classify as matched/drifted/missing</action>
+  <action if="story_has_figma_block">Calculate per-category drift percentages (color, typography, spacing, borders)</action>
+  <action if="story_has_figma_block">Save fidelity report to `{implementation_artifacts}/reviews/{story_key}/fidelity-report.md`</action>
+  <action if="story_has_figma_block">Write `figma.fidelity_drift_pct` to story file frontmatter</action>
+  <action if="story_has_figma_block">Include fidelity results in code review findings: PASS (0% drift), WARNING (any category exceeds 10%), or BLOCKED (any category exceeds 25%)</action>
+  <action if="no figma block">Skip fidelity check — story does not use Figma design tokens</action>
+</step>
 <step n="4" title="Generate Findings">
   <action>List issues by severity: critical, warning, suggestion</action>
 </step>

package/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/checklist.md

@@ -0,0 +1,25 @@
+---
+title: 'Create Stakeholder Validation'
+validation-target: 'Stakeholder file'
+---
+## Structure
+- [ ] workflow.yaml present with agent: orchestrator
+- [ ] instructions.xml present with sequential steps
+- [ ] checklist.md present
+- [ ] Registered in workflow-manifest.csv
+- [ ] Slash command file exists at .claude/commands/gaia-create-stakeholder.md
+## Input Collection
+- [ ] Required fields prompted: name, role, expertise, personality
+- [ ] Optional fields prompted: perspective, tags
+- [ ] Required field validation (non-empty check)
+## Validation Guards
+- [ ] 50-file cap enforced before file creation
+- [ ] Case-insensitive duplicate name detection against existing stakeholder name frontmatter
+- [ ] custom/stakeholders/ directory auto-created if missing
+## Output
+- [ ] Filename is kebab-case slug of name with .md extension
+- [ ] File written to custom/stakeholders/{slug}.md
+- [ ] YAML frontmatter includes all required fields
+- [ ] Optional fields included only when provided
+- [ ] Markdown body with ## Background section
+- [ ] File does not exceed 100 lines

package/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/instructions.xml

@@ -0,0 +1,79 @@
+<workflow name="create-stakeholder">
+<critical>
+  <mandate>Stakeholder files are written to custom/stakeholders/ — never to _gaia/</mandate>
+  <mandate>The 50-file cap and 100-line limit are hard gates (FR-164)</mandate>
+  <mandate>Duplicate name detection is case-insensitive against the name frontmatter field (FR-157)</mandate>
+</critical>
+
+<step n="1" title="Ensure Directory Exists">
+  <action>Check if {project-root}/custom/stakeholders/ directory exists</action>
+  <action if="directory does not exist">Create {project-root}/custom/stakeholders/ directory (and {project-root}/custom/ if needed)</action>
+  <action>Confirm directory is ready for writing</action>
+</step>
+
+<step n="2" title="Collect Required Inputs">
+  <ask>Provide the following required fields for the new stakeholder:
+
+  **Name** (display name, e.g., "Maria Santos"):
+  **Role** (title/function, e.g., "Housekeeper Manager"):
+  **Expertise** (domain skills, e.g., "Room turnover logistics"):
+  **Personality** (traits, e.g., "Pragmatic, detail-oriented"):
+  </ask>
+  <check if="any required field is empty">HALT: All four fields (name, role, expertise, personality) are required. Please provide all values.</check>
+</step>
+
+<step n="3" title="Collect Optional Inputs">
+  <ask>Optionally provide these additional fields (press Enter to skip):
+
+  **Perspective** (viewpoint/biases, e.g., "Focuses on operational efficiency"):
+  **Tags** (comma-separated, e.g., "operations, hospitality"):
+  </ask>
+</step>
+
+<step n="4" title="Validate Against Cap and Duplicates">
+  <action>Count existing .md files in {project-root}/custom/stakeholders/ directory</action>
+  <check if="count >= 50">HALT: The 50-file cap has been reached in custom/stakeholders/ (FR-164). There are already {count} stakeholder files. Remove unused stakeholders before creating new ones.</check>
+  <action>Scan all existing stakeholder files in custom/stakeholders/*.md — read the name field from each file's YAML frontmatter</action>
+  <action>Compare each existing name against the new stakeholder name using case-insensitive comparison</action>
+  <check if="duplicate name found (case-insensitive match)">HALT: A stakeholder with the name "{existing_name}" already exists at custom/stakeholders/{existing_file}. Name collision detected (case-insensitive). Choose a different name.</check>
+</step>
+
+<step n="5" title="Generate Filename Slug">
+  <action>Convert the stakeholder name to a kebab-case slug:
+    1. Convert to lowercase
+    2. Replace spaces with hyphens
+    3. Strip all characters that are not alphanumeric or hyphens
+    4. Collapse multiple consecutive hyphens into a single hyphen
+    5. Trim leading/trailing hyphens
+    6. Append .md extension
+  </action>
+  <action>Example: "Maria Santos" → "maria-santos.md", "Jean-Pierre O'Brien III" → "jean-pierre-obrien-iii.md"</action>
+  <action>Set output path: {project-root}/custom/stakeholders/{slug}.md</action>
+  <check if="file already exists at output path">HALT: File custom/stakeholders/{slug}.md already exists. This may indicate a slug collision from a different display name. Choose a different name or remove the existing file.</check>
+</step>
+
+<step n="6" title="Generate and Write Stakeholder File">
+  <action>Generate the stakeholder file with YAML frontmatter and Markdown body:
+
+  ```
+  ---
+  name: "{name}"
+  role: "{role}"
+  expertise: "{expertise}"
+  personality: "{personality}"
+  perspective: "{perspective}"    # Only include if provided
+  tags: [{tags_as_yaml_array}]    # Only include if provided
+  ---
+
+  ## Background
+
+  {A 2-3 sentence description synthesized from the provided fields, describing this stakeholder's viewpoint and discussion style.}
+  ```
+  </action>
+  <action>Verify the generated file does not exceed 100 lines. If it does, trim the Background section to fit within the limit.</action>
+  <action>Write the file to {project-root}/custom/stakeholders/{slug}.md</action>
+  <template-output file="{project-root}/custom/stakeholders/{slug}.md">
+    Stakeholder file with YAML frontmatter (name, role, expertise, personality, and optionally perspective and tags) plus a Markdown Background section.
+  </template-output>
+</step>
+</workflow>