gaia-framework 1.87.0 → 1.105.0

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

@@ -3,14 +3,20 @@
   <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>
+  <mandate>Verification mode must cross-reference generated test cases against execution results from JUnit XML, LCOV, or E17 evidence JSON sources (FR-222, FR-226)</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>
+  <action>If mode is 'coverage', proceed to Step 2 (coverage mode steps)</action>
+  <action>If mode is 'verification', proceed to Step 7 (verification mode steps)</action>
 </step>
 
+<!-- ======================== -->
+<!-- COVERAGE MODE: Steps 2-6 -->
+<!-- ======================== -->
+
 <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>
@@ -46,7 +52,60 @@
   </template-output>
 </step>
 
-<step n="6" title="Performance Validation">
+<step n="6" title="Performance Validation (Coverage Mode)">
+  <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>
+
+<!-- ================================= -->
+<!-- VERIFICATION MODE: Steps 7-11     -->
+<!-- FR-222, FR-226, ADR-030 §10.22    -->
+<!-- ================================= -->
+
+<step n="7" title="Scan Generated Test Cases (Verification Mode)">
+  <action>Scan docs/test-artifacts/ for all generated test case files and test plan references</action>
+  <action>Build a map of generated test cases per story: story_key -> [test_case_id, test_file, test_name]</action>
+  <action>Cross-reference generated test cases with story files in docs/implementation-artifacts/</action>
+  <action>Count total generated test cases per story and in aggregate</action>
+</step>
+
+<step n="8" title="Detect and Parse Execution Results (Verification Mode)">
+  <action>Scan for available test execution result files in the following formats:
+    1. JUnit XML files — parse test name, status (pass/fail/skip) from XML testcase elements
+    2. LCOV coverage files — parse source file coverage data and hit counts
+    3. E17 evidence JSON files — parse test IDs and execution status per the E17-S10 schema
+  </action>
+  <action>If no execution result files are found in any format (no JUnit XML, no LCOV, no evidence JSON):
+    Log warning: "No test execution results found — verification mode cannot determine executed test counts. Falling back to coverage mode output."
+    Graceful degradation: fallback to coverage mode output and skip remaining verification steps.
+    Proceed to Step 5 (coverage mode output generation) instead.</action>
+  <action>For each detected result format, extract: test identifier, execution status (passed/failed/skipped/unrun), and timestamp if available</action>
+  <action>Build a unified executed tests map: test_id -> {status, source_format, last_run}</action>
+</step>
+
+<step n="9" title="Cross-Reference Generated vs Executed (Verification Mode)">
+  <action>For each story, cross-reference its generated test cases against the executed tests map</action>
+  <action>Classify each generated test case as: EXECUTED (found in results with pass/fail status) or UNEXECUTED (not found in any result file)</action>
+  <action>Calculate per story counts: generated test cases count, executed test cases count</action>
+  <action>Calculate aggregate totals: total generated across all stories, total executed across all stories</action>
+  <action>Flag stories with zero executed tests as HIGH priority gaps — these stories have generated test cases but none have been run</action>
+</step>
+
+<step n="10" title="Generate Verification Output (FR-226 Schema)">
+  <action>Generate the output artifact at {test_artifacts}/test-gap-analysis-{date}.md in verification mode format</action>
+  <action>Output must include the following FR-226 schema sections:
+    - Summary section with total generated test count, total executed test count, and verification percentage
+    - Per-story generated-vs-executed count table listing each story with its generated count, executed count, and gap priority
+    - Aggregate generated-vs-executed count showing overall totals
+    - Unverified tests table listing test files with UNVERIFIED status and story key
+  </action>
+  <action>For stories with zero executed tests: set gap priority to HIGH in the per-story table</action>
+  <template-output file="{test_artifacts}/test-gap-analysis-{date}.md">
+    Verification mode gap analysis report with per-story and aggregate generated-vs-executed counts, HIGH priority flags for zero-executed stories.
+  </template-output>
+</step>
+
+<step n="11" title="Performance Validation (Verification Mode)">
   <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>

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

@@ -14,7 +14,9 @@ instructions: "{installed_path}/instructions.xml"
 validation: "{installed_path}/checklist.md"
 traces_to:
   - FR-221
+  - FR-222
   - FR-223
+  - FR-226
   - NFR-040
 performance_constraints:
   max_duration_seconds: 60  # NFR-040 — workflow must complete in under 60 seconds

package/gaia-install.sh

@@ -77,6 +77,7 @@ OPT_YES=false
 OPT_DRY_RUN=false
 OPT_VERBOSE=false
 OPT_BRANCH=""
+OPT_SKIP_SPRINT_GATE=false
 
 # ─── Utility Functions ──────────────────────────────────────────────────────
 
@@ -195,76 +196,10 @@ copy_with_backup() {
   [[ "$OPT_VERBOSE" == true ]] && detail "Updated (backed up): $dst" || true
 }
 
-# Remove .resolved/*.yaml files from target _gaia/ directory.
-# Called after cp/tar copy to replicate rsync's --exclude behavior.
-# Only .resolved/*.yaml is relevant to the _gaia/ subtree; the other rsync
-# --exclude patterns target _memory/ paths outside _gaia/ and never match.
-clean_resolved_yaml() {
-  local target_gaia="$1"
-  find "$target_gaia" -path '*/.resolved/*.yaml' -delete 2>/dev/null || true
-}
-
-# Copy _gaia/ directory from source to target using a fallback chain:
-#   rsync → cp -rp → tar
-# Tries each tool in order. If a tool is found but fails at runtime (e.g.,
-# broken rsync stub on Windows), falls through to the next tool. Exits with
-# a diagnostic error if all tools fail or none are available.
-#
-# Excludes .resolved/*.yaml files from the final output (rsync handles this
-# natively via --exclude; cp and tar do a post-copy cleanup).
-#
-# Note: No symlinks currently exist in _gaia/. If symlinks are introduced
-# in the future, verify that cp -rp behavior matches rsync -a on all
-# target platforms (ADR-004).
-copy_gaia_files() {
-  local src="$1" dst="$2"
-  local copy_done=false
-
-  # Try rsync first (preferred — handles excludes natively)
-  if command -v rsync >/dev/null 2>&1; then
-    if rsync -a \
-      --exclude='_memory/checkpoints/*.yaml' \
-      --exclude='_memory/checkpoints/completed/*.yaml' \
-      --exclude='.resolved/*.yaml' \
-      --exclude='_memory/*-sidecar/*.md' \
-      --exclude='_memory/*-sidecar/*.yaml' \
-      "$src/_gaia/" "$dst/_gaia/" 2>/dev/null; then
-      detail "Copied framework files using rsync"
-      copy_done=true
-    else
-      detail "rsync found but failed — trying fallback methods"
-    fi
-  fi
-
-  # Fallback: cp -rp (preserves permissions like rsync -a)
-  if [[ "$copy_done" == false ]] && command -v cp >/dev/null 2>&1; then
-    if cp -rp "$src/_gaia/." "$dst/_gaia/" 2>/dev/null; then
-      clean_resolved_yaml "$dst/_gaia"
-      detail "Copied framework files using cp -rp (rsync unavailable)"
-      copy_done=true
-    else
-      error "cp failed to copy framework files — check permissions and disk space"
-      exit 1
-    fi
-  fi
-
-  # Fallback: tar (last resort — available on virtually all POSIX systems)
-  if [[ "$copy_done" == false ]] && command -v tar >/dev/null 2>&1; then
-    if (tar -cf - -C "$src" _gaia | tar -xf - -C "$dst") 2>/dev/null; then
-      clean_resolved_yaml "$dst/_gaia"
-      detail "Copied framework files using tar (rsync and cp unavailable)"
-      copy_done=true
-    else
-      error "tar failed to copy framework files — check permissions and disk space"
-      exit 1
-    fi
-  fi
-
-  if [[ "$copy_done" == false ]]; then
-    error "No suitable copy tool found (tried rsync, cp, tar). Cannot copy framework files."
-    exit 1
-  fi
-}
+# Source extracted copy functions (clean_resolved_yaml, copy_gaia_files)
+# from lib/copy-lib.sh — E3-S11
+# shellcheck source=lib/copy-lib.sh
+source "$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/lib/copy-lib.sh"
 
 append_if_missing() {
   local file="$1" marker="$2" content="$3"
@@ -322,6 +257,53 @@ count_files() {
   find "$dir" -name "$pattern" -type f 2>/dev/null | wc -l | tr -d ' '
 }
 
+# ─── Sprint Gate (E18-S1, ADR-029 §10.21.2) ───────────────────────────────
+# Reads sprint-status.yaml and hard-blocks the upgrade if any story has an
+# active status (in-progress, review, or ready-for-dev).
+
+check_sprint_gate() {
+  local target="$1"
+  local sprint_file="$target/docs/implementation-artifacts/sprint-status.yaml"
+
+  # AC3: If no sprint file exists, gate passes silently
+  if [[ ! -f "$sprint_file" ]]; then
+    [[ "$OPT_VERBOSE" == true ]] && detail "No sprint-status.yaml found — sprint gate passes"
+    return 0
+  fi
+
+  # Extract sprint_id (top-level field, unindented)
+  local sprint_id
+  sprint_id="$(extract_yaml_value "$sprint_file" "sprint_id")"
+  [[ -z "$sprint_id" ]] && sprint_id="unknown"
+
+  # Count active stories — match only indented status: lines (story entries)
+  local active_count=0
+  while IFS= read -r line; do
+    local status_val
+    status_val="${line#*status:}"              # strip key
+    status_val="${status_val#"${status_val%%[![:space:]]*}"}"  # trim leading whitespace
+    status_val="${status_val#[\"\']}"           # trim leading quote
+    status_val="${status_val%[\"\']}"           # trim trailing quote
+    case "$status_val" in
+      in-progress|review|ready-for-dev)
+        active_count=$((active_count + 1))
+        ;;
+    esac
+  done < <(grep '^[[:space:]]\{1,\}status:' "$sprint_file")
+
+  # AC3: If no active stories, gate passes
+  if [[ "$active_count" -eq 0 ]]; then
+    [[ "$OPT_VERBOSE" == true ]] && detail "Sprint gate passes — no active stories"
+    return 0
+  fi
+
+  # AC2: Hard block with clear error message
+  local story_word="stories"
+  [[ "$active_count" -eq 1 ]] && story_word="story"
+  error "Upgrade blocked: sprint \`${sprint_id}\` is active (${active_count} ${story_word} in progress). Complete or pause the sprint before upgrading."
+  return 1
+}
+
 # ─── cmd_init ───────────────────────────────────────────────────────────────
 
 cmd_init() {
@@ -602,6 +584,15 @@ cmd_update() {
     [[ "$confirm" =~ ^[Yy] ]] || { info "Aborted."; exit 0; }
   fi
 
+  # Sprint Gate (E18-S1, ADR-029 §10.21.2): block upgrade if active sprint
+  if [[ "$OPT_SKIP_SPRINT_GATE" == true ]]; then
+    warn "Sprint gate bypassed via --skip-sprint-gate — proceed with caution"
+  else
+    if ! check_sprint_gate "$TARGET"; then
+      exit 1
+    fi
+  fi
+
   local timestamp
   timestamp="$(date +%Y%m%d-%H%M%S)"
   local backup_dir="$TARGET/_gaia/_backups/$timestamp"
@@ -995,12 +986,13 @@ ${BOLD}Commands:${RESET}
   status     Show installation info
 
 ${BOLD}Options:${RESET}
-  --source <path>   Local GAIA source (or clones from GitHub if omitted)
-  --branch <name>   Clone from a specific branch
-  --yes             Skip confirmation prompts
-  --dry-run         Show what would be done without making changes
-  --verbose         Show detailed progress
-  --help            Show this help message
+  --source <path>      Local GAIA source (or clones from GitHub if omitted)
+  --branch <name>      Clone from a specific branch
+  --yes                Skip confirmation prompts
+  --dry-run            Show what would be done without making changes
+  --verbose            Show detailed progress
+  --skip-sprint-gate   Bypass the active-sprint upgrade gate (NOT RECOMMENDED)
+  --help               Show this help message
 
 ${BOLD}Examples:${RESET}
   gaia-install.sh init ~/my-new-project
@@ -1070,6 +1062,10 @@ parse_args() {
         OPT_VERBOSE=true
         shift
         ;;
+      --skip-sprint-gate)
+        OPT_SKIP_SPRINT_GATE=true
+        shift
+        ;;
       --branch)
         if [[ -z "${2:-}" ]]; then
           error "--branch requires a branch name argument"

package/lib/copy-lib.sh

@@ -0,0 +1,81 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# copy-lib.sh — Extracted copy functions for gaia-install.sh
+# Origin: gaia-install.sh (E3-S11 — Extract copy_gaia_files for Unit Testability)
+#
+# This library is intentionally free of `set -euo pipefail`. The caller's
+# shell options govern execution. When BATS sources this directly, the BATS
+# process shell options apply. When gaia-install.sh sources it, the
+# installer's `set -euo pipefail` applies. Function bodies are neutral.
+# ─────────────────────────────────────────────────────────────────────────────
+
+# Remove .resolved/*.yaml files from target _gaia/ directory.
+# Called after cp/tar copy to replicate rsync's --exclude behavior.
+# Only .resolved/*.yaml is relevant to the _gaia/ subtree; the other rsync
+# --exclude patterns target _memory/ paths outside _gaia/ and never match.
+clean_resolved_yaml() {
+  local target_gaia="$1"
+  find "$target_gaia" -path '*/.resolved/*.yaml' -delete 2>/dev/null || true
+}
+
+# Copy _gaia/ directory from source to target using a fallback chain:
+#   rsync → cp -rp → tar
+# Tries each tool in order. If a tool is found but fails at runtime (e.g.,
+# broken rsync stub on Windows), falls through to the next tool. Exits with
+# a diagnostic error if all tools fail or none are available.
+#
+# Excludes .resolved/*.yaml files from the final output (rsync handles this
+# natively via --exclude; cp and tar do a post-copy cleanup).
+#
+# Note: No symlinks currently exist in _gaia/. If symlinks are introduced
+# in the future, verify that cp -rp behavior matches rsync -a on all
+# target platforms (ADR-004).
+copy_gaia_files() {
+  local src="$1" dst="$2"
+  local copy_done=false
+
+  # Try rsync first (preferred — handles excludes natively)
+  if command -v rsync >/dev/null 2>&1; then
+    if rsync -a \
+      --exclude='_memory/checkpoints/*.yaml' \
+      --exclude='_memory/checkpoints/completed/*.yaml' \
+      --exclude='.resolved/*.yaml' \
+      --exclude='_memory/*-sidecar/*.md' \
+      --exclude='_memory/*-sidecar/*.yaml' \
+      "$src/_gaia/" "$dst/_gaia/" 2>/dev/null; then
+      detail "Copied framework files using rsync"
+      copy_done=true
+    else
+      detail "rsync found but failed — trying fallback methods"
+    fi
+  fi
+
+  # Fallback: cp -rp (preserves permissions like rsync -a)
+  if [[ "$copy_done" == false ]] && command -v cp >/dev/null 2>&1; then
+    if cp -rp "$src/_gaia/." "$dst/_gaia/" 2>/dev/null; then
+      clean_resolved_yaml "$dst/_gaia"
+      detail "Copied framework files using cp -rp (rsync unavailable)"
+      copy_done=true
+    else
+      error "cp failed to copy framework files — check permissions and disk space"
+      exit 1
+    fi
+  fi
+
+  # Fallback: tar (last resort — available on virtually all POSIX systems)
+  if [[ "$copy_done" == false ]] && command -v tar >/dev/null 2>&1; then
+    if (tar -cf - -C "$src" _gaia | tar -xf - -C "$dst") 2>/dev/null; then
+      clean_resolved_yaml "$dst/_gaia"
+      detail "Copied framework files using tar (rsync and cp unavailable)"
+      copy_done=true
+    else
+      error "tar failed to copy framework files — check permissions and disk space"
+      exit 1
+    fi
+  fi
+
+  if [[ "$copy_done" == false ]]; then
+    error "No suitable copy tool found (tried rsync, cp, tar). Cannot copy framework files."
+    exit 1
+  fi
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-framework",
-  "version": "1.87.0",
+  "version": "1.105.0",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"
@@ -42,6 +42,7 @@
   },
   "files": [
     "bin/",
+    "lib/",
     "gaia-install.sh",
     "_gaia/",
     ".claude/",