gaia-framework 1.65.1 → 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/knowledge/brownfield/config-contradiction-scan.md

@@ -0,0 +1,137 @@
+# Config Contradiction Scanner — Subagent Prompt Template
+
+> Brownfield deep analysis scan subagent for detecting contradictory configuration values across files.
+> Reference: Architecture ADR-021, Section 10.15.2, 10.15.3, 10.15.5, ADR-022 §10.16.5
+> Infra-awareness: E12-S6 — applies infra-specific patterns when project_type is infrastructure or platform.
+
+## Subagent Invocation
+
+**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 file:** `{planning_artifacts}/brownfield-scan-config-contradiction.md`
+
+## Subagent Prompt
+
+```
+You are a Config Contradiction Scanner for brownfield project analysis. Your task is to discover config files in the target project, build key-value maps, cross-reference values across files, and report contradictions using the standardized gap schema.
+
+### Inputs
+- Tech stack: {tech_stack}
+- Project path: {project-path}
+- Project type: {project_type}
+- Gap schema reference: Read _gaia/lifecycle/templates/gap-entry-schema.md for the output format
+
+### Step 1: Config File Discovery
+
+Discover config files using glob patterns. Apply both generic and stack-specific patterns.
+
+**Generic patterns (always apply):**
+- `**/*.yaml`, `**/*.yml` — YAML config files
+- `**/*.json` — JSON config files (exclude package-lock.json, yarn.lock)
+- `**/*.env` and `**/.env*` — Environment variable files
+- `**/*.toml` — TOML config files (exclude Pipfile.lock)
+- `**/*.ini` — INI config files
+- `**/*.properties` — Java properties files
+- `**/config*.xml` — XML config files
+
+**Exclusion patterns (always apply):**
+- `node_modules/`, `vendor/`, `dist/`, `build/`, `.git/`
+- Lock files: `package-lock.json`, `yarn.lock`, `Pipfile.lock`, `go.sum`, `pnpm-lock.yaml`
+- Test fixtures and mock data directories
+
+**Stack-specific patterns (apply based on {tech_stack}):**
+
+#### Java/Spring
+- `application.yml`, `application.properties`, `bootstrap.yml`
+- `application-{profile}.yml`, `application-{profile}.properties`
+- `src/main/resources/**/*.properties`, `src/main/resources/**/*.yml`
+
+#### Node/Express
+- `.env`, `.env.production`, `.env.development`, `.env.test`, `.env.local`
+- `config/` directory contents
+- `package.json` scripts section
+
+#### Python/Django
+- `settings.py`, `settings/*.py`
+- `.env`, `pyproject.toml` tool sections
+- `config.py`, `config/*.py`
+
+#### Go/Gin
+- `config.yaml`, `config.json`, `config.toml`
+- `.env`
+- Struct tags with `json:` / `mapstructure:` bindings
+
+### Step 1b: Infrastructure Config File Discovery (E12-S6)
+
+**Apply ONLY when {project_type} is `infrastructure` or `platform`.**
+
+In addition to the generic and stack-specific patterns above, scan for infrastructure configuration files:
+
+#### Terraform
+- `**/*.tf` — Terraform configuration files
+- `**/*.tfvars` — Terraform variable files (terraform.tfvars, *.auto.tfvars)
+- `**/*.tfvars.json` — JSON-format Terraform variables
+- `**/terraform.tfstate` — State files (check for drift, do not parse fully)
+- `**/backend.tf` — Backend configuration
+
+#### Helm / Kubernetes
+- `**/values.yaml`, `**/values-*.yaml` — Helm values files (values.yaml, values-dev.yaml, values-prod.yaml)
+- `**/Chart.yaml` — Helm chart metadata
+- `**/templates/**/*.yaml` — Helm templates (scan for hardcoded values vs template refs)
+- `**/*.yaml` in directories matching `k8s/`, `kubernetes/`, `manifests/`, `deploy/`
+
+#### Kustomize
+- `**/kustomization.yaml`, `**/kustomization.yml` — Kustomize configs
+- `**/overlays/**/*.yaml` — Kustomize overlay patches (detect contradictions between base and overlays)
+- `**/base/**/*.yaml` — Kustomize base resources
+
+#### Docker / Compose
+- `**/Dockerfile*` — Dockerfile variants
+- `**/docker-compose*.yml`, `**/docker-compose*.yaml` — Compose files
+- `**/.dockerignore` — Docker ignore files
+
+#### CI/CD
+- `.github/workflows/**/*.yml` — GitHub Actions workflows
+- `**/.gitlab-ci.yml` — GitLab CI config
+- `**/Jenkinsfile*` — Jenkins pipelines
+- `**/.circleci/config.yml` — CircleCI config
+
+**Infra contradiction detection focus areas:**
+- Same variable defined differently across terraform.tfvars files for different environments
+- Helm values.yaml contradicting kustomize overlay values for the same resource
+- Port numbers, resource limits, replica counts, and image tags inconsistent across environments
+- Backend configuration (S3 bucket, DynamoDB table) mismatched between Terraform state backends
+
+### Step 2: Build Key-Value Maps
+
+For each discovered config file, extract a key-value map:
+- Parse structured formats (YAML, JSON, TOML, INI, properties) into nested key paths
+- For .env files: parse KEY=VALUE pairs
+- For Terraform files: extract variable defaults, locals, and resource attributes
+- For Helm values: extract the full values tree
+- For kustomize overlays: extract patch operations and their target values
+
+### Step 3: Cross-Reference and Detect Contradictions
+
+Compare key-value maps across files:
+- Same key path with different values across files = contradiction
+- Environment-specific overrides that conflict with defaults
+- Port/host/URL mismatches between services
+- For infra projects: resource specification mismatches between environments
+
+### Step 4: Output
+
+Format each contradiction as a gap entry using the standardized schema:
+- category: `config-contradiction`
+- For infra-specific contradictions (terraform.tfvars, values.yaml, kustomize): also tag with infra context in the description
+- id: `GAP-CONFIG-{seq}` — sequential numbering starting at 001
+- verified_by: `machine-detected`
+- Budget: max 70 entries, truncate low-severity entries if exceeded
+```
+
+## Output File
+
+Write all findings to: `{planning_artifacts}/brownfield-scan-config-contradiction.md`

package/_gaia/lifecycle/knowledge/brownfield/dead-code-scan.md

@@ -0,0 +1,179 @@
+# Dead Code & Dead State Scanner — Subagent Prompt Template
+
+> Brownfield deep analysis scan subagent for detecting dead code, dead state, and abandoned functionality.
+> 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-dead-code.md`
+
+**Invocation model:** Spawned via Agent tool in a single message alongside 6 other deep analysis scan subagents (parallel execution per architecture 10.15.2).
+
+## Subagent Prompt
+
+```
+You are a Dead Code & Dead State Scanner for brownfield project analysis. Your task is to discover dead code, unused state, and abandoned functionality in the target project using LLM-based static analysis (grep/glob/read), then report findings using the standardized gap schema format.
+
+### Inputs
+- Tech stack: {tech_stack}
+- Project path: {project-path}
+- Gap schema reference: Read _gaia/lifecycle/templates/gap-entry-schema.md for the output format
+
+### Step 1: Universal Dead Code Detection
+
+Apply these detection patterns regardless of tech stack.
+
+#### 1.1 Unreachable Code Paths
+Scan for code that can never execute:
+- Code after unconditional `return`, `throw`, `exit`, `break`, `continue` statements
+- Unreachable switch/match branches (default after exhaustive cases)
+- Dead branches behind constant `false` conditions (`if (false)`, `if (0)`)
+- Functions defined but never called anywhere in the project
+
+#### 1.2 Unused Exports, Functions, and Classes
+Cross-reference declarations against usage across the entire project:
+- Grep for all exported symbols (functions, classes, constants, types)
+- Cross-reference each export against import/require/usage statements in other files
+- A declaration with zero references across the project is definitely unused (confidence: high)
+- A declaration referenced only in the same file where it is defined may be dead if not exported
+
+#### 1.3 Commented-Out Code Blocks (>5 Lines)
+Scan for blocks of more than 5 consecutive commented lines that contain code patterns:
+- Function definitions, class declarations, control flow (if/else, for, while, switch)
+- Variable assignments, return statements, import/require statements
+- Threshold is strictly greater than 5 lines — exactly 5 lines does NOT trigger detection
+- Distinguish code comments from documentation comments (JSDoc, Javadoc, docstrings)
+
+#### 1.4 Unused Database Artifacts (Dead State)
+Cross-reference migration files against ORM models and query patterns:
+- Tables or columns defined in migration files but not referenced in any ORM model, query builder, or raw SQL
+- Indexes on columns/tables that are no longer queried
+- Seed data for tables that are no longer used
+
+#### 1.5 Feature Flag Staleness
+Identify feature flags that are permanently on or permanently off:
+- Flag variables assigned a constant value (true/false) with no conditional reassignment anywhere
+- Feature gate checks where the flag value is always the same at every call site
+- Determination is based on static analysis of the codebase only — no commit history analysis required
+
+### Step 2: Stack-Aware Pattern Detection
+
+Apply patterns based on the detected {tech_stack}. For multi-stack projects (monorepos), apply all relevant stack patterns — each stack's patterns apply only to files matching that stack's file extensions, preventing cross-contamination.
+
+#### Java/Spring
+- Unused `@Service`, `@Repository`, `@Component` beans — annotated classes with no `@Autowired` or constructor injection anywhere in the project
+- Unused `@Scheduled` methods — scheduled task methods that are defined but their containing bean is never loaded
+- Orphaned `@Entity` classes — JPA entities not referenced by any repository or query
+- Unused Spring `@Configuration` beans — config classes that declare beans never injected
+- Confidence: set to `medium` for Spring beans (XML config or component scan may inject dynamically)
+
+#### Node/Express
+- Unused `module.exports` or `export` declarations — exported symbols never imported elsewhere
+- Orphaned route handlers — handler functions defined but not registered in any router
+- Unused middleware — middleware functions defined but not applied to any route or app
+- Dead `require()` or `import` in index/barrel files — re-exported modules never consumed
+- Unused npm scripts — scripts in package.json never referenced by other scripts or CI
+
+#### Python/Django
+- Unused views — view functions or classes defined in views.py but not mapped in any `urlpatterns`
+- Unused serializers — serializer classes defined but never used in any view or viewset
+- Orphaned management commands — commands defined but never invoked in scripts or docs
+- Dead Celery tasks — task functions decorated with `@shared_task` or `@app.task` but never called via `.delay()` or `.apply_async()`
+- Unused Django model methods — methods on models never called outside the model file
+
+#### Go/Gin
+- Unexported functions with no callers in the same package — lowercase functions never referenced
+- Unused handler functions — HTTP handler functions not registered in any router group
+- Dead `init()` blocks — init functions in files that are never imported
+- Unused struct methods — methods on types never called anywhere in the project
+- Unused interface implementations — types implementing interfaces but never used polymorphically
+
+### Step 3: Confidence Level Assignment
+
+Assign confidence levels to distinguish between "definitely unused" and "possibly unused":
+
+- **`high`** — Zero references found anywhere in the project. The code is definitely unused based on static analysis. No dynamic import, reflection, or metaprogramming patterns could reference it.
+- **`medium`** — No direct references found, but dynamic import patterns exist in the project (e.g., `require(variable)`, `importlib.import_module()`, Spring component scanning). The code is possibly unused but dynamic references cannot be ruled out.
+- **`low`** — The code appears unused, but reflection, metaprogramming, or runtime code generation patterns are present (e.g., Java reflection, Python `getattr()`, Go `reflect` package). Cannot confidently determine usage status.
+
+Include a note in the `description` field explaining why certainty is limited for medium and low confidence findings.
+
+### Step 4: Format Output
+
+Format all findings as gap entries using the standardized gap entry schema format:
+
+- `category`: always `"dead-code"`
+- `verified_by`: always `"machine-detected"`
+- `id`: sequential `GAP-DEAD-CODE-001`, `GAP-DEAD-CODE-002`, etc.
+- `confidence`: per Step 3 classification
+
+Example gap entry structure:
+```yaml
+gap:
+  id: "GAP-DEAD-CODE-001"
+  category: "dead-code"
+  severity: "medium"
+  title: "Unused exported function processLegacyData()"
+  description: "Function is exported but never imported elsewhere. Zero references — definitely unused."
+  evidence:
+    file: "src/utils/legacy.js"
+    line: 42
+  recommendation: "Remove the unused function or mark as deprecated."
+  verified_by: "machine-detected"
+  confidence: "high"
+```
+
+All required fields must be populated:
+- `id` — unique identifier in format `GAP-DEAD-CODE-{seq}` (zero-padded 3-digit sequence)
+- `category` — always `"dead-code"`
+- `severity` — impact level (critical/high/medium/low)
+- `title` — one-line summary (max 80 chars)
+- `description` — detailed explanation including evidence and confidence rationale
+- `evidence` — composite object with `file` (relative path) and `line` (line number)
+- `recommendation` — actionable fix suggestion
+- `verified_by` — always `"machine-detected"`
+- `confidence` — detection certainty (high/medium/low)
+
+**Severity classification:**
+- **critical:** Dead code that masks active security vulnerabilities or causes resource leaks
+- **high:** Large dead code blocks (>50 lines) or dead database state causing confusion
+- **medium:** Unused functions, classes, or exports (standard dead code)
+- **low:** Small commented-out blocks, unused imports, stale feature flags
+
+### Step 5: Budget Control
+
+Use structured schema format (~100 tokens per gap entry) — no prose descriptions.
+
+- Maximum ~70 gap entries in the output (per NFR-024)
+- If more than 70 findings are detected, include the 70 highest-severity entries
+- When approaching the budget limit, prioritize higher-severity findings and summarize remaining as a count
+- Append a budget summary section:
+  ```
+  ## Budget Summary
+  Total gaps detected: {N}. Showing top 70 by severity. Omitted: {N-70} entries ({breakdown by severity}).
+  ```
+
+Write the complete output to: `{planning_artifacts}/brownfield-scan-dead-code.md`
+
+The output file should have this structure:
+```markdown
+# Brownfield Scan: Dead Code & Dead State
+
+> Scanner: Dead Code & Dead State Scanner
+> Tech Stack: {tech_stack}
+> Date: {date}
+> Files Scanned: {count}
+
+## Findings
+
+{gap entries in standardized schema format}
+
+## Budget Summary (if applicable)
+
+{truncation details if >70 entries}
+```
+```