gaia-framework 1.66.0 → 1.87.0

package/.claude/commands/gaia-create-stakeholder.md

@@ -0,0 +1,20 @@
+---
+name: 'create-stakeholder'
+description: 'Scaffold a new stakeholder file for Party Mode. Use when "create a stakeholder".'
+model: sonnet
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. PARSE arguments from $ARGUMENTS:
+   - Check for "yolo" keyword (case-insensitive): if present, set yolo_mode=true
+2. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+3. READ its entire contents — this is the CORE OS
+4. Pass {project-root}/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/workflow.yaml as 'workflow-config'
+5. If yolo_mode=true: tell the engine "Run in YOLO mode — auto-proceed past all template-outputs."
+6. Follow workflow.xml instructions EXACTLY
+7. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/.claude/commands/gaia-test-gap-analysis.md

@@ -0,0 +1,17 @@
+---
+name: 'test-gap-analysis'
+description: 'Scan test suite against requirements to identify coverage gaps. Use when "test gap analysis".'
+model: opus
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS:
+
+<steps CRITICAL="TRUE">
+1. LOAD the FULL {project-root}/_gaia/core/engine/workflow.xml
+2. READ its entire contents — this is the CORE OS
+3. Pass {project-root}/_gaia/testing/workflows/test-gap-analysis/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/CLAUDE.md

@@ -1,5 +1,7 @@
 
-# GAIA Framework v1.66.0
+# GAIA Framework
+
+> Version: see `package.json` or `_gaia/_config/global.yaml`
 
 This project uses the **GAIA** (Generative Agile Intelligence Architecture) framework — an AI agent framework for Claude Code that orchestrates software product development through 26 specialized agents, 65 workflows, and 8 shared skills.
 
@@ -168,6 +170,90 @@ For infrastructure stories (those whose `traces_to` field contains `IR-###`, `OR
 
 Agent memory sidecars accumulate decisions across sessions. Run `/gaia-memory-hygiene` periodically (recommended before each sprint) to detect stale, contradicted, or orphaned entries by cross-referencing sidecar decisions against current planning and architecture artifacts.
 
+## Branching Model
+
+This project uses a three-tier branch flow:
+
+```
+feature branches → staging → main
+```
+
+- **Feature branches** — all development happens on feature branches. Never commit directly to `staging` or `main`.
+- **`staging`** — integration branch for release candidates. Merging a PR to `staging` triggers an automated version bump and produces an RC prerelease version (e.g., `1.66.0-rc.1`). Each subsequent merge increments the RC counter (e.g., `1.66.0-rc.2`).
+- **`main`** — production branch. Merging a promotion PR from `staging` to `main` strips the `-rc.N` suffix and produces the release version (e.g., `1.66.0`).
+
+**Example version flow:**
+```
+main 1.65.1 → PR bump:patch → staging 1.65.2-rc.1 → PR bump:none → staging 1.65.2-rc.2 → promote → main 1.65.2
+```
+
+## Version Bumping
+
+**CRITICAL: Do NOT bump versions manually.** Version bumping is fully automated via GitHub Actions, triggered by PR merges.
+
+### How it works
+
+- When a PR is merged to `staging`, the `version-bump-staging.yml` workflow reads the PR's bump label and updates the version automatically.
+- Version state lives in **2 files only**: `package.json` and `_gaia/_config/global.yaml`.
+- `gaia-install.sh` reads version dynamically from `package.json` at runtime — it does not carry a hardcoded version.
+- `manifest.yaml`, `CLAUDE.md`, and `README.md` do not carry version numbers.
+
+### Bump labels
+
+Every PR merged to `staging` must have exactly one `bump:*` label:
+
+| Label | Effect | Example |
+|-------|--------|---------|
+| `bump:major` | Bump 1st number, reset 2nd+3rd, set RC=1 | `1.65.1` → `2.0.0-rc.1` |
+| `bump:minor` | Bump 2nd number, reset 3rd, set RC=1 | `1.65.1` → `1.66.0-rc.1` |
+| `bump:patch` | Bump 3rd number, set RC=1 | `1.65.1` → `1.65.2-rc.1` |
+| `bump:none` | Keep version numbers, increment RC only | `1.65.2-rc.1` → `1.65.2-rc.2` |
+
+### What NOT to do
+
+- Do NOT run `npm run version:bump` — this command no longer exists
+- Do NOT manually edit version numbers in `package.json` or `global.yaml`
+- Do NOT bump versions in feature branches — version changes happen automatically on merge to `staging`
+
+## Branch Protection
+
+Both `staging` and `main` branches are protected in GitHub settings:
+
+- **PR required** — no direct push allowed to either branch
+- **Status checks required** — lint, security audit, and tests must pass before merge
+- **Bump label enforcement** — PRs to `staging` are blocked without exactly one `bump:*` label (`bump:major`, `bump:minor`, `bump:patch`, or `bump:none`)
+
+Branch protection is configured in GitHub repository settings, not in code.
+
+## Git Discipline
+
+- Always commit AND push after completing changes. Do not leave unpushed commits.
+- Write clear, conventional commit messages focused on what changed and why.
+- Always use feature branches — NEVER commit directly to `staging` or `main`.
+- PR workflow: feature branch → `staging` (with bump label) → `main` (promotion PR).
+
+## npm Publishing
+
+Publishing is fully automated — no manual steps required beyond creating the promotion PR.
+
+### Automated pipeline
+
+1. **Feature development:** develop on a feature branch, create PR to `staging` with a `bump:*` label
+2. **Staging merge:** `version-bump-staging.yml` bumps the version and commits the RC version to `staging`
+3. **Promotion:** create a PR from `staging` to `main`
+4. **Release:** `promote-to-main.yml` strips the `-rc.N` suffix, commits the release version, creates a git tag `vX.Y.Z`, and creates a GitHub Release
+5. **Publish:** the GitHub Release triggers `publish.yml`, which runs tests, verifies the version matches the tag, and publishes to npm with provenance attestation
+
+### What NOT to do
+
+- Do NOT manually create git tags — tags are created automatically by `promote-to-main.yml`
+- Do NOT manually run `gh release create` — releases are created automatically
+- Do NOT manually run `npm publish` — publishing is triggered by the GitHub Release
+
+### Verification
+
+After a release, verify: `npm view gaia-framework version`
+
 ## Do Not
 
 - Pre-load files — load at runtime when needed

package/README.md

@@ -1,6 +1,6 @@
 # GAIA — Generative Agile Intelligence Architecture
 
-[![Framework](https://img.shields.io/badge/framework-v1.66.0-blue)]()
+[![Framework](https://img.shields.io/badge/framework-GAIA-blue)]()
 [![License](https://img.shields.io/badge/license-AGPL--3.0-green)]()
 [![Agents](https://img.shields.io/badge/agents-26-purple)]()
 [![Workflows](https://img.shields.io/badge/workflows-73-orange)]()
@@ -460,7 +460,7 @@ The single source of truth is `_gaia/_config/global.yaml`:
 
 ```yaml
 framework_name: "GAIA"
-framework_version: "1.66.0"
+framework_version: "<current>"
 user_name: "your-name"
 project_name: "your-project"
 ```

package/_gaia/_config/global.yaml

@@ -3,7 +3,7 @@
 # After modifying this file, run /gaia-build-configs to regenerate resolved configs.
 
 framework_name: "GAIA"
-framework_version: "1.66.0"
+framework_version: "1.87.0"
 
 # User settings
 user_name: "jlouage"
@@ -39,6 +39,10 @@ sizing_map:
   L: 8
   XL: 13
 
+# Problem-solving workflow — context gathering configuration
+problem_solving:
+  context_budget: 30000  # Max tokens for auto-gathered context (Step 0)
+
 # Framework paths
 installed_path: "{project-root}/_gaia"
 config_path: "{project-root}/_gaia/_config"

package/_gaia/_config/lifecycle-sequence.yaml

@@ -450,6 +450,15 @@ sequence:
       standalone: true
       note: "Run periodically to detect stale or contradicted decisions in agent memory sidecars"
 
+  create-stakeholder:
+    module: lifecycle
+    command: /gaia-create-stakeholder
+    next:
+      standalone: true
+      suggestions:
+        - command: /gaia-party
+          context: "To start a Party Mode discussion with the new stakeholder"
+
   performance-review:
     module: lifecycle
     command: /gaia-performance-review
@@ -549,6 +558,17 @@ sequence:
         - command: /gaia-run-all-reviews
           context: "To complete the review gate"
 
+  test-gap-analysis:
+    module: testing
+    command: /gaia-test-gap-analysis
+    next:
+      standalone: true
+      suggestions:
+        - command: /gaia-test-design
+          context: "To design tests covering newly identified coverage gaps"
+        - command: /gaia-test-automate
+          context: "To automate tests filling the identified gaps"
+
   traceability:
     module: testing
     command: /gaia-trace

package/_gaia/_config/skill-manifest.csv

@@ -7,8 +7,10 @@ name,displayName,description,path,applicable_agents
 "code-review-standards","Code Review Standards","Universal review checklist, SOLID, complexity metrics","_gaia/dev/skills/code-review-standards.md","all-dev"
 "documentation-standards","Documentation Standards","README templates, ADRs, inline comments, API docs","_gaia/dev/skills/documentation-standards.md","all-dev,tech-writer,analyst,pm"
 "security-basics","Security Basics","OWASP Top 10, input validation, secrets, CORS/CSRF","_gaia/dev/skills/security-basics.md","all-dev,architect,security,devops"
+"figma-integration","Figma Integration","Figma MCP detection probe, design tokens (W3C DTCG), component specs, frame generation, asset export, per-stack resolution","_gaia/dev/skills/figma-integration.md","all-dev"
 "validation-patterns","Validation Patterns","Claim extraction, filesystem verification, cross-reference, severity classification, findings formatting","_gaia/lifecycle/skills/validation-patterns.md","validator"
 "ground-truth-management","Ground Truth Management","Entry structure, incremental/full refresh, conflict resolution, archival, token budget, brownfield extraction","_gaia/lifecycle/skills/ground-truth-management.md","validator"
 "memory-management","Memory Management","Session load/save, decision formatting, stale detection, deduplication, context summarization, cross-ref loading, budget-monitoring","_gaia/lifecycle/skills/memory-management.md","all"
 "memory-management-cross-agent","Memory Management Cross-Agent","Cross-agent memory read protocol for loading other agents' sidecar files","_gaia/lifecycle/skills/memory-management-cross-agent.md","all"
 "document-rulesets","Document Rulesets","Artifact type detection, document-specific validation rulesets (prd, arch, ux, test-plan, epics), two-pass validation logic","_gaia/lifecycle/skills/document-rulesets.md","validator"
+"figma-integration","Figma Integration","Design tool detection, token extraction (W3C DTCG), component specs, frame generation, asset export, per-stack resolution","_gaia/dev/skills/figma-integration.md","all-dev"

package/_gaia/_config/workflow-manifest.csv

@@ -33,7 +33,7 @@ name,displayName,description,module,phase,path,command,agent
 "quick-dev","Quick Dev","Implement a quick spec","lifecycle","quick-flow","_gaia/lifecycle/workflows/quick-flow/quick-dev/workflow.yaml","gaia-quick-dev","dev-*"
 "design-thinking","Design Thinking","Guide human-centered design process","creative","anytime","_gaia/creative/workflows/design-thinking/workflow.yaml","gaia-design-thinking","design-thinking-coach"
 "innovation-strategy","Innovation Strategy","Identify disruption opportunities","creative","anytime","_gaia/creative/workflows/innovation-strategy/workflow.yaml","gaia-innovation","innovation-strategist"
-"problem-solving","Problem Solving","Apply systematic problem-solving methodologies","creative","anytime","_gaia/creative/workflows/problem-solving/workflow.yaml","gaia-problem-solving","problem-solver"
+"problem-solving","Problem Solving","Apply systematic problem-solving methodologies with resolution routing","creative","anytime","_gaia/creative/workflows/problem-solving/workflow.yaml","gaia-problem-solving","problem-solver"
 "storytelling","Storytelling","Craft compelling narratives","creative","anytime","_gaia/creative/workflows/storytelling/workflow.yaml","gaia-storytelling","storyteller"
 "teach-me-testing","Teach Me Testing","Teach testing progressively","testing","anytime","_gaia/testing/workflows/teach-me-testing/workflow.yaml","gaia-teach-testing","test-architect"
 "edit-test-plan","Edit Test Plan","Edit an existing test plan — add test cases without regenerating","testing","anytime","_gaia/testing/workflows/edit-test-plan/workflow.yaml","gaia-edit-test-plan","test-architect"
@@ -45,6 +45,7 @@ name,displayName,description,module,phase,path,command,agent
 "test-review","Test Review","Review test quality","testing","anytime","_gaia/testing/workflows/test-review/workflow.yaml","gaia-test-review","test-architect"
 "nfr-assessment","NFR Assessment","Assess non-functional requirements","testing","anytime","_gaia/testing/workflows/nfr-assessment/workflow.yaml","gaia-nfr","test-architect"
 "traceability","Traceability","Generate traceability matrix","testing","anytime","_gaia/testing/workflows/traceability/workflow.yaml","gaia-trace","test-architect"
+"test-gap-analysis","Test Gap Analysis","Scan test suite against requirements to identify coverage gaps","testing","anytime","_gaia/testing/workflows/test-gap-analysis/workflow.yaml","gaia-test-gap-analysis","test-architect"
 "security-threat-model","Security Threat Model","Create STRIDE/DREAD threat model","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/security-threat-model/workflow.yaml","gaia-threat-model","security"
 "security-review","Security Review","Pre-merge OWASP security review","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/security-review/workflow.yaml","gaia-security-review","security"
 "infrastructure-design","Infrastructure Design","Design deployment topology and IaC","lifecycle","3-solutioning","_gaia/lifecycle/workflows/3-solutioning/infrastructure-design/workflow.yaml","gaia-infra-design","devops"
@@ -73,3 +74,4 @@ name,displayName,description,module,phase,path,command,agent
 "run-all-reviews","Run All Reviews","Runs all 6 review workflows sequentially via subagents","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/run-all-reviews/workflow.yaml","gaia-run-all-reviews","orchestrator"
 "check-review-gate","Check Review Gate","Check composite review gate status and transition story to done if all reviews pass","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/check-review-gate/workflow.yaml","gaia-check-review-gate","sm"
 "action-items","Action Items","Process and resolve action items from retro, triage, tech-debt, and correct-course","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/action-items/workflow.yaml","gaia-action-items","orchestrator"
+"create-stakeholder","Create Stakeholder","Scaffold new stakeholder file for Party Mode","lifecycle","4-implementation","_gaia/lifecycle/workflows/4-implementation/create-stakeholder/workflow.yaml","gaia-create-stakeholder","orchestrator"

package/_gaia/core/engine/workflow.xml

@@ -74,7 +74,11 @@ execution modes (normal/yolo/planning), checkpoints, and quality gates.
     <action if="agent is 'dev-*' (wildcard)">Check if workflow.yaml declares agent_auto_detect: true. If true, execute the agent_auto_detect_strategy from workflow.yaml to determine the stack. If auto-detection succeeds, resolve to {project-root}/_gaia/dev/agents/{detected_stack}-dev.md and inform user: "Auto-detected developer: {agent_name} based on {detection_source}." If auto-detection fails or agent_auto_detect is false/absent: ask user which stack developer to use (typescript, angular, flutter, java, python, mobile, go), then resolve to {project-root}/_gaia/dev/agents/{stack}-dev.md</action>
     <action if="agent file resolved">Read the agent persona file — adopt its persona, name, communication style, rules, and domain knowledge for the duration of this workflow</action>
     <action if="agent file resolved">Do NOT execute the agent's activation protocol, greeting, or menu — the workflow engine controls step execution</action>
-    <action if="agent file resolved">Check for {project-root}/_gaia/_config/agents/{agent-id}.customize.yaml. If found, load and merge overrides (persona_overrides, menu_additions, menu_removals, skill_additions, rule_additions, skill_overrides, skill_section_overrides). For dev agents, also check all-dev.customize.yaml and merge (agent-specific takes precedence over all-dev).</action>
+    <action if="agent file resolved">Check for .customize.yaml using the following lookup order (file-level replacement — no merge between locations; if found in custom/skills/, skip _gaia/_config/agents/ entirely):
+      1. Check {project-root}/custom/skills/{agent-id}.customize.yaml — primary location (survives framework upgrades)
+      2. Fall back to {project-root}/_gaia/_config/agents/{agent-id}.customize.yaml — legacy/default location (silent fallback, no error or warning if custom/skills/ file does not exist)
+      For dev agents, also check custom/skills/all-dev.customize.yaml before _gaia/_config/agents/all-dev.customize.yaml (same file-level replacement semantics — if found in custom/skills/, skip _gaia/_config/agents/ entirely).
+      If a .customize.yaml is found at either location, load and merge overrides (persona_overrides, menu_additions, menu_removals, skill_additions, rule_additions, skill_overrides, skill_section_overrides). Agent-specific takes precedence over all-dev.</action>
 
     <!-- Memory Load Protocol (E9-S7) — Load agent memory sidecar files after persona, before instructions -->
     <action if="agent file resolved">Read {project-root}/_memory/config.yaml to resolve agent tier and sidecar path. If the file does not exist, log "Memory config not found — skipping memory loading." and skip all remaining memory load actions in this step.</action>

package/_gaia/core/workflows/party-mode/steps/step-01-agent-loading.md

@@ -1,11 +1,62 @@
 # Step 1: Agent Loading
 
-1. Read `_gaia/_config/agent-manifest.csv` to discover all installed agents
-2. Ask the user which agents to invite to the discussion:
-   - Option A: "All agents" — load all from manifest
-   - Option B: "By module" — let user pick modules (lifecycle, dev, creative, testing)
-   - Option C: "Specific agents" — let user pick individual agents by name
-3. For each selected agent, load their persona (name, title, communication_style, principles)
-4. Do NOT load full agent files — only extract persona summaries
-5. Present the guest list to the user for confirmation
-6. Ask for the discussion topic or question
+<!-- References: architecture.md#10.18.2, ADR-026, FR-158/159/160/161, NFR-029 -->
+
+## Source 1: GAIA Agent Discovery
+
+1. Read `_gaia/_config/agent-manifest.csv` to discover all installed GAIA agents
+2. For each agent row, extract: name, displayName, title, module
+3. Build the GAIA agent list (existing behavior, unchanged)
+
+## Source 2: Stakeholder Discovery
+
+4. Glob `custom/stakeholders/*.md` to discover stakeholder persona files
+   - If the `custom/stakeholders/` directory does not exist, silently produce zero stakeholders — no error, no warning
+   - Skip empty files (0 bytes) silently
+   - If a file has malformed YAML frontmatter, skip it with a warning: "Skipping {filename}: invalid YAML frontmatter" — do not crash discovery
+5. Parse only YAML frontmatter from each discovered stakeholder file — extract: name (required), role (required), tags (optional)
+   - The `tags` field is an optional array in frontmatter (e.g., `tags: ["hotel-ops", "cleaning"]`)
+   - Build a tag-to-stakeholder index: map each tag to the list of stakeholders whose `tags` array contains it
+   - Stakeholders with multiple tags appear in the index under every tag they have
+   - If a stakeholder has no `tags` field or an empty array, it is excluded from tag-based searches but remains available for individual selection
+   - Do NOT load the full Markdown body at discovery time — frontmatter only
+6. Enforce 50-file cap: if more than 50 stakeholder files are found, warn "Stakeholder cap exceeded: {count} files found, using first 50 alphabetically" and truncate to the first 50 sorted alphabetically
+7. Track token budget during frontmatter scan — estimate each file's frontmatter at ~100 tokens (approx 400 chars). Total discovery across all stakeholder files must stay within 5K token budget (NFR-029). If cumulative budget reaches 80%, warn and stop scanning additional files.
+8. If `custom/stakeholders/` does not exist or is empty, display hint: "Tip: Create stakeholder personas with `/gaia-create-stakeholder` to invite domain experts to discussions." (FR-162)
+
+## Merge and Display Invite List
+
+9. Build a combined invite list from GAIA agents (Source 1) and stakeholders (Source 2)
+   - GAIA agents display as: `{displayName} — {title} ({module})`
+   - Stakeholders display with an `[S]` marker: `[S] {name} — {role}`
+10. Name disambiguation (FR-159): compare each stakeholder name against GAIA agent displayNames (case-insensitive). If a collision is detected, prefix the stakeholder with `[Stakeholder]` in the invite list and during discussion. GAIA agents always take precedence — agents retain their original name unchanged.
+11. Ask the user which participants to invite:
+    - Option A: "All agents" — GAIA agents only (unchanged from original behavior)
+    - Option B: "By module" — let user pick GAIA modules: lifecycle, dev, creative, testing (unchanged)
+    - Option C: "Specific agents" — let user pick individual participants from the combined GAIA + stakeholder list
+    - Option D: "Stakeholders only" — let user pick from stakeholders only (FR-160). This creates a valid stakeholder-only party with zero GAIA agents.
+    - Option E: "By tag" — invite stakeholders matching a tag (FR-161)
+      - Prompt the user for a tag name
+      - Look up the tag in the tag-to-stakeholder index (case-insensitive matching)
+      - All stakeholders whose `tags` array contains the specified tag are invited
+      - If the tag matches zero stakeholders, display warning: "Tag '{tag}' matches no stakeholders" and continue with any other invitees
+      - Tag-based invitations can be combined alongside individual agent/stakeholder name selections in the same invitation
+      - Alternative syntax: "invite all {tag}" (e.g., "invite all hotel-ops") — parsed and resolved using the same tag index with case-insensitive matching
+
+## Validation
+
+12. Validate the selection:
+    - Zero GAIA agents + one or more stakeholders = valid party — the orchestrator manages discussion flow (FR-160)
+    - One or more GAIA agents + zero stakeholders = valid party (original behavior)
+    - One or more GAIA agents + one or more stakeholders = valid party
+    - Zero GAIA agents + zero stakeholders = invalid party — halt with message: "Cannot start party: no agents or stakeholders selected. Select at least one participant."
+
+## Load Participant Personas
+
+13. For each selected GAIA agent: load their persona (name, title, communication_style, principles) — do NOT load full agent files, only extract persona summaries
+14. For each selected stakeholder: use the frontmatter already parsed at discovery time for the persona summary. Full file content (Markdown body) is loaded JIT when the stakeholder actually participates in discussion — not at selection time. If a stakeholder file exceeds 100 lines, display a warning when the full file is loaded: "Stakeholder file {filename} exceeds 100 lines — consider trimming for optimal context usage."
+
+## Confirm and Proceed
+
+15. Present the guest list to the user for confirmation
+16. Ask for the discussion topic or question

package/_gaia/creative/workflows/problem-solving/checklist.md

@@ -1,26 +1,76 @@
 # Problem Solving Checklist
 
-## Problem Framing
+## Phase 1: Intake
+
+### Problem Intake
+- [ ] Problem statement captured from user
+- [ ] Urgency level classified (critical / high / medium / low)
+- [ ] Domain keywords extracted and semantically expanded
+
+### Context Gathering
+- [ ] Tier 1 artifact scan completed:
+  - [ ] Story files searched for keyword matches
+  - [ ] Architecture doc scanned for affected components
+  - [ ] PRD scanned for relevant requirements
+  - [ ] Agent decision logs checked (PM, architect, SM sidecars)
+  - [ ] Test artifacts checked for coverage and gaps
+- [ ] Tier 2 codebase scan completed (if technical problem):
+  - [ ] Source code grepped for affected routes/services/components
+  - [ ] Recent git history checked for affected area
+  - [ ] Related test files identified
+- [ ] Context Brief synthesized within 30K token budget
+- [ ] Context Brief presented to user for validation
+- [ ] User confirmed or added missing context
+
+## Phase 2: Context-Informed Analysis
+
+### Context-Informed vs Fallback Behavior
+- [ ] context_brief_available flag correctly determined from Step 2 checkpoint
+- [ ] When Context Brief available: steps read context from checkpoint (not user interrogation)
+- [ ] When Context Brief available: user only asked for information NOT in the Context Brief
+- [ ] When Context Brief unavailable (Step 0 skipped or empty): steps fall back to interrogation-based behavior
+- [ ] Fallback mode operates with no errors and no degraded experience
+
+### Problem Framing
 - [ ] Problem clearly articulated (not a symptom)
-- [ ] Success criteria defined
-- [ ] Stakeholders and impact identified
+- [ ] Symptoms separated from root causes using artifact evidence (or user input in fallback mode)
+- [ ] Success criteria defined (grounded in existing acceptance criteria, or user goals in fallback mode)
 
-## Root Cause Analysis
+### Root Cause Analysis
 - [ ] Methodology applied (5 Whys, Fishbone, TRIZ)
-- [ ] Root cause identified and validated
+- [ ] Root cause identified with artifact evidence (or user-provided evidence in fallback mode)
 - [ ] Causal chain documented
+- [ ] Root cause validated — fixing it fixes the symptoms
+- [ ] Test gap identified (what test should have caught this)
+- [ ] `test_gaps` array populated (AC4): each entry has file_path, gap_description, suggested_test_type, severity
+- [ ] `test_gaps` uses correct schema: file_path (string), gap_description (string), suggested_test_type (unit/integration/e2e), severity (critical/high/medium/low)
+- [ ] `test_gaps` is empty array (not absent) when no gaps found
+- [ ] `test_gaps` persisted to workflow checkpoint for downstream steps
 
-## Constraints
-- [ ] Real constraints separated from assumptions
-- [ ] Each constraint challenged and verified
+### Constraints
+- [ ] Real constraints verified against ADRs and decision logs (or user input in fallback mode)
+- [ ] Assumed constraints challenged with evidence
 - [ ] Contradictions identified
 
-## Solutions
+### Solutions
 - [ ] At least 5 candidate solutions generated
 - [ ] Solutions address root cause, not symptoms
-- [ ] Feasibility/impact/effort assessed
+- [ ] Solutions cross-checked against architecture constraints (from Context Brief or user input)
+- [ ] Feasibility/impact/effort assessed (grounded in codebase context or user estimates in fallback mode)
+- [ ] Rejected solutions documented with clear reasoning
+
+## Phase 3: Resolution Routing
+
+### Classification
+- [ ] Resolution classified (quick fix / bug / critical / enhancement / systemic)
+- [ ] Classification confirmed by user
 
-## Action Plan
-- [ ] Concrete next steps defined
-- [ ] Owners and timelines assigned
-- [ ] Success metrics specified
+### Resolution Execution
+- [ ] Problem-solving artifact saved to {creative_artifacts}/
+- [ ] Resolution path executed:
+  - [ ] Quick fix / Bug / Critical: /gaia-create-story invoked with pre-populated context
+  - [ ] Enhancement: /gaia-add-feature invoked with problem-solving artifact
+  - [ ] Systemic: Problem Brief generated and escalation target identified
+- [ ] Story includes origin: problem-solving and origin_ref fields (if story created)
+- [ ] `test_gaps` array carried into story Dev Notes (if story created)
+- [ ] Completion summary presented with next steps