gaia-framework 1.66.0 → 1.83.2

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

@@ -12,6 +12,8 @@ points: "{story_points}"
 risk: "{high/medium/low}"
 sprint_id: null
 priority_flag: null
+origin: null
+origin_ref: null
 depends_on: []
 blocks: []
 traces_to: []
@@ -116,4 +118,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,61 @@
   <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="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.
   </template-output>
 </step>
-<step n="8" title="Optional: Accessibility Review">
+<step n="14" 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="15" 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/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>

package/_gaia/lifecycle/workflows/4-implementation/create-stakeholder/workflow.yaml

@@ -0,0 +1,22 @@
+name: create-stakeholder
+description: 'Scaffold a new stakeholder file for Party Mode discussions'
+module: lifecycle
+agent: orchestrator
+config_resolved: "{installed_path}/.resolved/create-stakeholder.yaml"
+config_source: "{project-root}/_gaia/lifecycle/config.yaml"
+installed_path: "{project-root}/_gaia/lifecycle/workflows/4-implementation/create-stakeholder"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+quality_gates:
+  pre_start: []
+  post_complete:
+    - check: "stakeholder_file_line_count_valid == true"
+      on_fail: "HALT: Stakeholder file exceeds 100-line limit (FR-164). Edit {project-root}/custom/stakeholders/{slug}.md to reduce content or re-run /gaia-create-stakeholder."
+    - check: "stakeholder_count_in_directory_valid == true"
+      on_fail: "HALT: custom/stakeholders/ has more than 50 files (FR-164). Remove unused stakeholders from {project-root}/custom/stakeholders/ first."
+on_error:
+  missing_file: "ask_user"
+  unresolved_variable: "halt"
+
+output:
+  primary: "{project-root}/custom/stakeholders/{slug}.md"

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

@@ -94,6 +94,14 @@
 <step n="6" title="Generate Output">
   <action>Read the story template from the engine-resolved template path. The engine resolves this in Step 1 (Load and Resolve Config): if {project-root}/custom/templates/story-template.md exists and is non-empty, the custom template is used; otherwise it falls back to {project-root}/_gaia/lifecycle/templates/story-template.md. Use whichever path the engine resolved.</action>
   <action>Read sizing_map from {project-root}/_gaia/_config/global.yaml to resolve T-shirt size to story points (S→2, M→5, L→8, XL→13).</action>
+  <action>Detect invocation context to determine origin fields:
+    If invoked from problem-solving routing (E16-S3): set origin="problem-solving" and origin_ref to the path of the Problem Brief or problem-solving checkpoint artifact (e.g., docs/creative-artifacts/problem-solving-YYYY-MM-DD.md).
+    If invoked from triage routing: set origin="triage" and origin_ref to the triage artifact path.
+    If invoked from add-feature routing: set origin="add-feature" and origin_ref to the source artifact path.
+    If invoked from sprint-planning: set origin="sprint-planning" and origin_ref to the sprint plan artifact path.
+    If invoked with explicit origin parameters from caller: use the provided origin and origin_ref values.
+    If invoked normally (no routing context): set origin=null and origin_ref=null (planned work default).
+  </action>
   <action>Populate ALL YAML frontmatter fields from epics-and-stories.md data:
     - key: story key from epics (e.g., E1-S1)
     - title: story title
@@ -110,6 +118,8 @@
     - date: current date
     - author: agent name (e.g., "Nate (Scrum Master)")
     - priority_flag: null (default — set to "next-sprint" by add-feature for high-urgency stories)
+    - origin: workflow origin (null for planned work, "problem-solving" from problem-solving routing, "triage" from triage, "add-feature" from add-feature routing, "sprint-planning" from sprint planning, "manual" for explicit manual creation)
+    - origin_ref: path to source artifact that triggered story creation (null when origin is null)
   </action>
   <template-output file="{implementation_artifacts}/{story_key}-{story_title_slug}.md">
     Generate the story file following the story-template.md structure. The filename must use the story key and slugified title (e.g., E1-S1-user-login.md). Include complete YAML frontmatter with ALL 15 fields populated. Fill all template sections: User Story, Acceptance Criteria, Tasks/Subtasks (linked to AC numbers), Dev Notes, Technical Notes, Dependencies, Test Scenarios, Project Structure Notes, References, Dev Agent Record, and Estimate. IMPORTANT: The body "**Status:**" line MUST match the frontmatter status field exactly. Both must say the same status value.

package/_gaia/lifecycle/workflows/4-implementation/retrospective/instructions.xml

@@ -108,14 +108,14 @@
 
     3. Apply the improvement: append to or modify the relevant section in custom/skills/{skill-name}.md with comment "<!-- Added from retro-{sprint_id}: {reason} -->".
 
-    4. Register in .customize.yaml: after writing the custom skill file, register it in {project-root}/_gaia/_config/agents/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs.
-       - If all-dev.customize.yaml does not exist: create it with proper YAML structure:
+    4. Register in .customize.yaml: after writing the custom skill file, register it in {project-root}/custom/skills/all-dev.customize.yaml so the engine loads from the custom path on subsequent runs (ADR-020 — customization registries live alongside custom skills in custom/skills/).
+       - If custom/skills/all-dev.customize.yaml does not exist: create it with proper YAML structure:
          ```yaml
          skill_overrides:
            {skill-name}:
              source: "custom/skills/{skill-name}.md"
          ```
-       - If all-dev.customize.yaml already exists: read current content, check if a skill_overrides entry for this skill already exists. If it does not exist, append the new entry under skill_overrides. Preserve all existing entries — only add the new one. If it already exists (duplicate), skip registration to prevent duplicate entries.
+       - If custom/skills/all-dev.customize.yaml already exists: read current content, check if a skill_overrides entry for this skill already exists. If it does not exist, append the new entry under skill_overrides. Preserve all existing entries — only add the new one. If it already exists (duplicate), skip registration to prevent duplicate entries.
   </action>
   <action>If no skill improvements identified, state: "No skill improvements identified this sprint."</action>
 </step>

package/_gaia/lifecycle/workflows/4-implementation/validate-story/instructions.xml

@@ -45,6 +45,17 @@
       (file paths, component references, API endpoints, dependency versions).
       Verify against filesystem and ground truth (if available).
       Classify findings as CRITICAL (broken reference), WARNING (outdated), INFO (style).
+
+  (g) Origin Field Validation (optional fields — backward compatible):
+      The origin and origin_ref fields are OPTIONAL — stories without these fields
+      are valid (backward compatibility). Missing origin/origin_ref fields do NOT
+      cause errors and are accepted without warnings.
+      If the origin field IS present, validate:
+        - origin must be one of: "manual", "problem-solving", "triage", "add-feature",
+          "sprint-planning", or null. An invalid origin enum value is a CRITICAL finding.
+        - If origin is non-null, origin_ref must be non-empty (not null, not empty string).
+          A non-null origin with empty or null origin_ref is a WARNING finding.
+      If origin is null or absent, origin_ref is not validated (orphaned refs are acceptable).
   </action>
 </step>
 <step n="3" title="Validation Fix Loop">

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/instructions.xml

@@ -124,23 +124,26 @@
   **Step 1 — Load all scan outputs:**
   Load gap entries from ALL of the following sources. For each file, if it exists, parse YAML gap entries matching the schema from gap-entry-schema.md. If a file is empty or missing, log a warning noting which scanner produced no results and continue processing the remaining files without error.
 
-  Deep analysis scan outputs (7 files):
+  Deep analysis scan outputs (7 files — Step 2.5):
   - {planning_artifacts}/brownfield-scan-config-contradiction.md
   - {planning_artifacts}/brownfield-scan-dead-code.md
-  - {planning_artifacts}/brownfield-scan-hard-coded-logic.md
-  - {planning_artifacts}/brownfield-scan-security-endpoint.md
+  - {planning_artifacts}/brownfield-scan-hardcoded.md
+  - {planning_artifacts}/brownfield-scan-security.md
   - {planning_artifacts}/brownfield-scan-runtime-behavior.md
-  - {planning_artifacts}/brownfield-scan-doc-code-drift.md
+  - {planning_artifacts}/brownfield-scan-doc-code.md
   - {planning_artifacts}/brownfield-scan-integration-seam.md
 
-  Step 2 documentation subagent outputs:
+  Test execution scan output (1 file — Step 2.75):
+  - {planning_artifacts}/brownfield-scan-test-execution.md (failing tests as gap entries)
+
+  Step 2 documentation subagent outputs (4 files):
   - {planning_artifacts}/api-documentation.md (API gaps)
   - {planning_artifacts}/event-catalog.md (event/messaging gaps)
   - {planning_artifacts}/ux-design.md (frontend/UX gaps)
   - {planning_artifacts}/dependency-map.md (dependency gaps)
 
-  Step 3 test execution results:
-  - {test_artifacts}/nfr-assessment.md (test execution gap findings)
+  Step 3 NFR assessment:
+  - {test_artifacts}/nfr-assessment.md (NFR gap findings)
 
   **Step 2 — Validate entries against schema:**
   For each parsed gap entry, validate that all required fields are present: id, category, severity, title, description (or evidence), evidence_file, evidence_line, recommendation. Entries missing any required field are logged as warnings (noting the source file and which field is missing) and skipped from consolidation rather than causing a failure.
@@ -197,6 +200,7 @@
   — If infrastructure: use IR-### for infrastructure requirements, OR-### for operational requirements, and SR-### for security requirements exclusively. Do NOT use FR/NFR prefixes.
   — If platform: use BOTH ID scheme families — FR-###/NFR-### for application-layer requirements and IR-###/OR-###/SR-### for infrastructure-layer requirements. All requirement IDs are globally unique within the project — the prefix disambiguates (e.g., FR-001 and IR-001 are distinct, no collision).</action>
   <action>Read upstream artifacts to inform gap analysis:</action>
+  <action>— project-documentation.md → project context: tech stack, architecture patterns, conventions, detected capability flags, CI/CD summary. Use for PRD Overview section (existing project summary) and to ground gap requirements in the actual project structure.</action>
   <action>— consolidated-gaps.md → primary input: deduplicated, ranked, and code-verified gap list from Steps 3.5 and 5.5. If a '## Verification Corrections for PRD' section exists, use it to correct factual errors from contradicted claims.</action>
   <action>— nfr-assessment.md → NFR section gets real "Current Baseline" and "Target" columns</action>
   <action>— api-documentation.md (if exists) → extract API gaps (undocumented endpoints, missing validation)</action>

package/_gaia/testing/workflows/test-gap-analysis/checklist.md

@@ -0,0 +1,8 @@
+# Test Gap Analysis Checklist
+- [ ] Execution mode determined (coverage or verification)
+- [ ] Test plan scanned for test case IDs and story links
+- [ ] Story files scanned for acceptance criteria
+- [ ] Cross-reference completed — gaps identified
+- [ ] Output follows FR-223 schema (summary count, per-story table, coverage %)
+- [ ] Zero-gap case handled with "No coverage gaps detected" message
+- [ ] Workflow completed within NFR-040 performance constraint (< 60 seconds)

package/_gaia/testing/workflows/test-gap-analysis/instructions.xml

@@ -0,0 +1,53 @@
+<workflow name="test-gap-analysis">
+<critical>
+  <mandate>Scan test-plan.md and story files to identify acceptance criteria gaps — NFR-040 requires completion in under 60 seconds</mandate>
+  <mandate>Output must follow the FR-223 schema: summary count, per-story gap table, coverage percentage</mandate>
+  <mandate>When no gaps are detected, output must state "No coverage gaps detected" with a summary count of zero</mandate>
+</critical>
+
+<step n="1" title="Determine Mode">
+  <action>Check the --mode argument: coverage or verification</action>
+  <action>If no mode specified, default to coverage mode</action>
+  <action>If mode is 'verification', skip to verification-mode steps (E19-S2 scope — not implemented yet)</action>
+</step>
+
+<step n="2" title="Scan Test Plan">
+  <action>Read {test_artifacts}/test-plan.md</action>
+  <action>Extract all test case IDs and their linked story keys from the test plan</action>
+  <action>Build a map of test_case_id -> [story_keys] for cross-referencing</action>
+  <action>If test-plan.md is missing, log warning: "test-plan.md not found — partial coverage analysis only" and continue with empty test case map</action>
+</step>
+
+<step n="3" title="Scan Story Files">
+  <action>Scan all story files in docs/implementation-artifacts/ matching pattern {story_key}-*.md</action>
+  <action>For each story file, extract all acceptance criteria (AC items) from the "Acceptance Criteria" section</action>
+  <action>Build a map of story_key -> [AC items] with their identifiers (AC1, AC2, etc.)</action>
+  <action>Track untested acceptance criteria — ACs that have no matching test case in the test plan map</action>
+</step>
+
+<step n="4" title="Cross-Reference and Identify Gaps">
+  <action>For each story's acceptance criteria, check if a corresponding test case exists in the test plan</action>
+  <action>Flag each AC as covered (has test case) or uncovered-ac (no test case found)</action>
+  <action>Calculate coverage rate per story: covered_ACs / total_ACs</action>
+  <action>Calculate overall coverage percentage across all stories</action>
+</step>
+
+<step n="5" title="Generate Output (FR-223 Schema)">
+  <action>Generate the output artifact at {test_artifacts}/test-gap-analysis-{date}.md</action>
+  <action>Output must include the following FR-223 schema sections:
+    - Summary section with total count of stories analyzed, ACs scanned, gaps found, and overall coverage percentage
+    - Per-story gap table listing each story, its ACs, and their coverage status
+    - Coverage rate breakdown showing covered vs uncovered acceptance criteria
+  </action>
+  <action>If zero gaps are detected (all ACs have corresponding test cases):
+    Output "No coverage gaps detected" in the summary section with a gap count of 0 and coverage rate of 100%</action>
+  <template-output file="{test_artifacts}/test-gap-analysis-{date}.md">
+    Gap analysis report following FR-223 schema with summary count, per-story gap table, and coverage percentage.
+  </template-output>
+</step>
+
+<step n="6" title="Performance Validation">
+  <action>Verify workflow completed within the NFR-040 constraint of under 60 seconds</action>
+  <action>Log total execution time in the output footer</action>
+</step>
+</workflow>

package/_gaia/testing/workflows/test-gap-analysis/workflow.yaml

@@ -0,0 +1,38 @@
+name: test-gap-analysis
+description: 'Scan test suite against requirements to identify untested or under-tested areas'
+module: testing
+agent: test-architect
+execution_mode: planning
+modes:
+  - coverage
+  - verification
+default_mode: coverage
+config_resolved: "{installed_path}/.resolved/test-gap-analysis.yaml"
+config_source: "{project-root}/_gaia/testing/config.yaml"
+installed_path: "{project-root}/_gaia/testing/workflows/test-gap-analysis"
+instructions: "{installed_path}/instructions.xml"
+validation: "{installed_path}/checklist.md"
+traces_to:
+  - FR-221
+  - FR-223
+  - NFR-040
+performance_constraints:
+  max_duration_seconds: 60  # NFR-040 — workflow must complete in under 60 seconds
+input_file_patterns:
+  test_plan:
+    whole: "{test_artifacts}/test-plan.md"
+    load_strategy: "FULL_LOAD"
+  story_files:
+    whole: "{implementation_artifacts}/*.md"
+    load_strategy: "INDEX_GUIDED"
+  architecture:
+    whole: "{planning_artifacts}/architecture.md"
+    load_strategy: "INDEX_GUIDED"
+  sprint_status:
+    whole: "{implementation_artifacts}/sprint-status.yaml"
+    load_strategy: "FULL_LOAD"
+output:
+  primary: "{test_artifacts}/test-gap-analysis-{date}.md"
+on_error:
+  missing_file: "warn_and_continue"
+  unresolved_variable: "halt"

package/bin/gaia-framework.js

@@ -158,6 +158,8 @@ Commands:
   status     Show installation info
 
 Options:
+  --branch <name>   Clone from a specific branch
+  --staging         Shorthand for --branch staging
   --yes             Skip confirmation prompts
   --dry-run         Show what would be done without making changes
   --verbose         Show detailed progress
@@ -207,6 +209,32 @@ function main(deps) {
     fail(`Unknown command: ${command}\n   Run 'npx gaia-framework --help' for usage.`);
   }
 
+  // ─── Branch flag parsing (E14-S1) ─────────────────────────────────────────
+  // Extract --branch / --staging before building the passthrough array.
+  // These flags control which git branch is cloned — they are consumed by the
+  // JS CLI and forwarded as --branch <name> to gaia-install.sh.
+  let branchValue = null;
+  const remaining = args.slice(0);
+
+  const branchIdx = remaining.indexOf("--branch");
+  const hasStaging = remaining.includes("--staging");
+
+  if (branchIdx >= 0 && hasStaging) {
+    fail("Cannot use --branch and --staging together. Use --branch staging instead.");
+  }
+
+  if (branchIdx >= 0) {
+    const valueIdx = branchIdx + 1;
+    if (valueIdx >= remaining.length || remaining[valueIdx].startsWith("--")) {
+      fail("Missing value for --branch flag. Usage: --branch <name>");
+    }
+    branchValue = remaining[valueIdx];
+    remaining.splice(branchIdx, 2);
+  } else if (hasStaging) {
+    branchValue = "staging";
+    remaining.splice(remaining.indexOf("--staging"), 1);
+  }
+
   // Ensure git is available
   ensureGit();
 
@@ -237,8 +265,9 @@ function main(deps) {
 
   info("Cloning GAIA framework from GitHub...");
 
+  const branchCloneFlag = branchValue ? ` --branch ${branchValue}` : "";
   try {
-    _exec(`git clone --depth 1 ${REPO_URL} "${tempDir}"`, {
+    _exec(`git clone --depth 1${branchCloneFlag} ${REPO_URL} "${tempDir}"`, {
       stdio: ["ignore", "ignore", "pipe"],
     });
   } catch (err) {
@@ -256,10 +285,15 @@ function main(deps) {
 
   // Build the shell command: inject --source pointing to the temp clone
   // so the shell script doesn't need to clone again
-  const passthrough = args.slice(0);
+  const passthrough = remaining.slice(0);
   // Insert --source right after the command (convert to POSIX for bash on Windows)
   passthrough.splice(1, 0, "--source", toPosixPath(tempDir));
 
+  // Inject --branch flag for installer passthrough (E14-S1)
+  if (branchValue) {
+    passthrough.push("--branch", branchValue);
+  }
+
   // Locate bash (critical for Windows support)
   const bashPath = _findBash();
   if (!bashPath) {

package/bin/helpers/derive-bump-label.js

@@ -0,0 +1,41 @@
+/**
+ * Derive bump label from PR title conventional commit prefix.
+ * Used by .github/workflows/pr-title-label.yml (E14-S11, ADR-025).
+ *
+ * @param {string} title - PR title
+ * @param {string} body - PR body
+ * @returns {{ label: string, type: string, breaking: boolean } | null}
+ *   Returns the derived bump label info, or null if title doesn't match.
+ */
+
+const TITLE_REGEX = /^(feat|fix|refactor|perf|test|docs|chore|ci|style)(\(.+\))?(!)?: .+$/;
+
+const TYPE_TO_LABEL = Object.freeze({
+  feat: "bump:minor",
+  fix: "bump:patch",
+  perf: "bump:patch",
+  refactor: "bump:none",
+  test: "bump:none",
+  docs: "bump:none",
+  chore: "bump:none",
+  ci: "bump:none",
+  style: "bump:none",
+});
+
+function deriveBumpLabel(title, body) {
+  const match = title.match(TITLE_REGEX);
+  if (!match) return null;
+
+  const type = match[1];
+  const bang = match[3] === "!";
+  const bodyBreaking = typeof body === "string" && body.includes("BREAKING CHANGE");
+  const breaking = bang || bodyBreaking;
+
+  const label = breaking ? "bump:major" : TYPE_TO_LABEL[type];
+
+  return { label, type, breaking };
+}
+
+module.exports = deriveBumpLabel;
+module.exports.TITLE_REGEX = TITLE_REGEX;
+module.exports.TYPE_TO_LABEL = TYPE_TO_LABEL;

package/bin/helpers/validate-bump-labels.js

@@ -0,0 +1,38 @@
+/**
+ * PR bump label validation for staging merge enforcement.
+ * Used by .github/workflows/label-check.yml (E14-S6, ADR-025).
+ */
+
+const VALID_BUMP_LABELS = Object.freeze(["bump:major", "bump:minor", "bump:patch", "bump:none"]);
+
+/**
+ * Validate that exactly one bump:* label is present on a PR.
+ *
+ * @param {string[]} labels - Array of label names from the PR
+ * @returns {{ pass: boolean, message: string }} Validation result
+ */
+function validateBumpLabels(labels) {
+  const bumpLabels = labels.filter((label) => VALID_BUMP_LABELS.includes(label));
+
+  if (bumpLabels.length === 0) {
+    return {
+      pass: false,
+      message: `No bump label found. Add one of: ${VALID_BUMP_LABELS.join(", ")}`,
+    };
+  }
+
+  if (bumpLabels.length > 1) {
+    return {
+      pass: false,
+      message: `Multiple bump labels found: ${bumpLabels.join(", ")}. Exactly one required.`,
+    };
+  }
+
+  return {
+    pass: true,
+    message: `Valid bump label: ${bumpLabels[0]}`,
+  };
+}
+
+module.exports = validateBumpLabels;
+module.exports.VALID_BUMP_LABELS = VALID_BUMP_LABELS;