gaia-framework 1.65.1 → 1.83.2

package/_gaia/lifecycle/workflows/anytime/brownfield-onboarding/workflow.yaml

@@ -30,4 +30,5 @@ output:
     - "{planning_artifacts}/prd.md"
     - "{planning_artifacts}/architecture.md"
     - "{planning_artifacts}/epics-and-stories.md"
+    - "{planning_artifacts}/brownfield-scan-test-execution.md"
     - "{planning_artifacts}/brownfield-onboarding.md"

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
@@ -183,6 +185,8 @@ function main(deps) {
   const _join = (deps && deps.join) || join;
   const _mkdtemp = (deps && deps.mkdtempSync) || mkdtempSync;
   const _tmpdir = (deps && deps.tmpdir) || tmpdir;
+  const _isWindows = deps && typeof deps.isWindows === "boolean" ? deps.isWindows : IS_WINDOWS;
+  const _findBash = (deps && deps.findBash) || findBash;
 
   const args = process.argv.slice(2);
 
@@ -205,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();
 
@@ -212,13 +242,13 @@ function main(deps) {
   tempDir = _mkdtemp(_join(_tmpdir(), "gaia-framework-"));
   // Resolve 8.3 short names to long paths on Windows (e.g., ELIASN~1 → Elias Nasser)
   // Node's realpathSync doesn't expand 8.3 names, so use PowerShell
-  if (IS_WINDOWS) {
+  if (_isWindows) {
     try {
-      const longPath = execSync(
+      const longPath = _exec(
         `powershell -NoProfile -Command "(Get-Item -LiteralPath '${tempDir}').FullName"`,
         { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
       ).trim();
-      if (longPath && existsSync(longPath)) tempDir = longPath;
+      if (longPath && _exists(longPath)) tempDir = longPath;
     } catch {}
   }
 
@@ -235,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) {
@@ -254,12 +285,17 @@ 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();
+  const bashPath = _findBash();
   if (!bashPath) {
     fail(
       "bash is required but was not found.\n" +
@@ -273,12 +309,12 @@ function main(deps) {
   try {
     // Convert all passthrough args that look like paths (contain backslash or drive letter)
     const posixArgs = passthrough.map((a) =>
-      IS_WINDOWS && /[\\:]/.test(a) && !a.startsWith("--") ? toPosixPath(a) : a
+      _isWindows && /[\\:]/.test(a) && !a.startsWith("--") ? toPosixPath(a) : a
     );
     const posixScript = toPosixPath(scriptPath);
 
     // Debug: on Windows, log the resolved paths if --verbose is passed
-    if (IS_WINDOWS && args.includes("--verbose")) {
+    if (_isWindows && args.includes("--verbose")) {
       info(`Bash: ${bashPath} (${bashType})`);
       info(`Script (Windows): ${scriptPath}`);
       info(`Script (POSIX): ${posixScript}`);

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;

package/gaia-install.sh

@@ -76,6 +76,7 @@ TARGET=""
 OPT_YES=false
 OPT_DRY_RUN=false
 OPT_VERBOSE=false
+OPT_BRANCH=""
 
 # ─── Utility Functions ──────────────────────────────────────────────────────
 
@@ -95,7 +96,11 @@ clone_from_github() {
   fi
   TEMP_CLONE_DIR="$(mktemp -d "${TMPDIR:-/tmp}/gaia-framework-XXXXXX")"
   info "Cloning GAIA from GitHub..." >&2
-  if git clone --depth 1 "$GITHUB_REPO" "$TEMP_CLONE_DIR" 2>/dev/null; then
+  local branch_args=()
+  if [[ -n "$OPT_BRANCH" ]]; then
+    branch_args=(--branch "$OPT_BRANCH")
+  fi
+  if git clone --depth 1 "${branch_args[@]}" "$GITHUB_REPO" "$TEMP_CLONE_DIR" 2>/dev/null; then
     success "Cloned to temporary directory" >&2
   else
     error "Failed to clone from $GITHUB_REPO"
@@ -233,7 +238,7 @@ copy_gaia_files() {
 
   # 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
+    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
@@ -493,16 +498,18 @@ cmd_init() {
     fi
   fi
 
-  # Step 8: Create custom skills directory
-  step "Creating custom skills directory..."
-  if [[ "$OPT_DRY_RUN" == true ]]; then
-    detail "[dry-run] Would create: custom/skills/"
-  else
-    mkdir -p "$TARGET/custom/skills"
-  fi
-  if [[ -f "$source/custom/skills/README.md" ]]; then
-    copy_if_missing "$source/custom/skills/README.md" "$TARGET/custom/skills/README.md"
-  fi
+  # Step 8: Create custom directories (ADR-020: user-owned write targets)
+  step "Creating custom directories..."
+  for cdir in skills templates stakeholders; do
+    if [[ "$OPT_DRY_RUN" == true ]]; then
+      detail "[dry-run] Would create: custom/$cdir/"
+    else
+      mkdir -p "$TARGET/custom/$cdir"
+    fi
+    if [[ -f "$source/custom/$cdir/README.md" ]]; then
+      copy_if_missing "$source/custom/$cdir/README.md" "$TARGET/custom/$cdir/README.md"
+    fi
+  done
 
   # Step 9: Append GAIA entries to .gitignore
   step "Updating .gitignore..."
@@ -626,6 +633,35 @@ cmd_update() {
     "_config/manifest.yaml"
   )
 
+  # ─── Migrate .customize.yaml files before _gaia/ overwrite (E10-S19, FR-153) ──
+  # Copy user customize.yaml files from _gaia/_config/agents/ to custom/skills/
+  # before the framework overwrite replaces _gaia/ contents with defaults.
+  # Copy-only semantics: originals are left in place as fallback (AC2).
+  step "Migrating customize.yaml files to custom/skills/..."
+  if [[ "$OPT_DRY_RUN" != true ]]; then
+    mkdir -p "$TARGET/custom/skills"
+  fi
+  local migrated=0
+  for cust_file in "$TARGET/_gaia/_config/agents/"*.customize.yaml; do
+    [[ -f "$cust_file" ]] || continue
+    local cust_basename
+    cust_basename="$(basename "$cust_file")"
+    if [[ -f "$TARGET/custom/skills/$cust_basename" ]]; then
+      [[ "$OPT_VERBOSE" == true ]] && detail "Skipped (already exists): custom/skills/$cust_basename"
+      continue
+    fi
+    if [[ "$OPT_DRY_RUN" == true ]]; then
+      detail "[dry-run] Would migrate: _gaia/_config/agents/$cust_basename → custom/skills/$cust_basename"
+    else
+      cp "$cust_file" "$TARGET/custom/skills/$cust_basename"
+      info "[migrate] _gaia/_config/agents/$cust_basename → custom/skills/$cust_basename"
+      migrated=$((migrated + 1))
+    fi
+  done
+  if [[ "$migrated" -gt 0 ]]; then
+    detail "Migrated $migrated customize.yaml file(s) to custom/skills/"
+  fi
+
   step "Updating framework files..."
   local updated=0 skipped=0 changed=0
 
@@ -687,15 +723,17 @@ cmd_update() {
     fi
   done
 
-  # Ensure custom skills directory exists (user-owned, never overwritten)
-  if [[ "$OPT_DRY_RUN" == true ]]; then
-    [[ ! -d "$TARGET/custom/skills" ]] && detail "[dry-run] Would create: custom/skills/"
-  else
-    mkdir -p "$TARGET/custom/skills"
-  fi
-  if [[ -f "$source/custom/skills/README.md" ]]; then
-    copy_if_missing "$source/custom/skills/README.md" "$TARGET/custom/skills/README.md"
-  fi
+  # Ensure custom directories exist (user-owned, never overwritten — ADR-020)
+  for cdir in skills templates stakeholders; do
+    if [[ "$OPT_DRY_RUN" == true ]]; then
+      [[ ! -d "$TARGET/custom/$cdir" ]] && detail "[dry-run] Would create: custom/$cdir/"
+    else
+      mkdir -p "$TARGET/custom/$cdir"
+    fi
+    if [[ -f "$source/custom/$cdir/README.md" ]]; then
+      copy_if_missing "$source/custom/$cdir/README.md" "$TARGET/custom/$cdir/README.md"
+    fi
+  done
 
   # Update slash commands (add new ones, update existing with backup)
   step "Updating slash commands..."
@@ -736,6 +774,29 @@ cmd_update() {
     fi
   fi
 
+  # ─── Post-install verification: check skill references in customize.yaml (E10-S19, AC4) ──
+  step "Verifying skill references in custom/skills/*.customize.yaml..."
+  for cust_file in "$TARGET/custom/skills/"*.customize.yaml; do
+    [[ -f "$cust_file" ]] || continue
+    local cust_name
+    cust_name="$(basename "$cust_file")"
+    # Extract source: values from customize.yaml (simple grep — no full YAML parser needed)
+    while IFS= read -r source_line; do
+      # Strip key prefix, leading whitespace, and surrounding quotes via parameter expansion
+      local ref_path="${source_line#*source:}"
+      ref_path="${ref_path#"${ref_path%%[![:space:]]*}"}"  # trim leading whitespace
+      ref_path="${ref_path#[\"\']}"                        # trim leading quote
+      ref_path="${ref_path%[\"\']}"                        # trim trailing quote
+      [[ -z "$ref_path" ]] && continue
+      # Resolve relative paths against TARGET
+      local full_path="$TARGET/$ref_path"
+      [[ "$ref_path" == /* ]] && full_path="$ref_path"
+      if [[ ! -f "$full_path" ]]; then
+        warn "[warn] Broken skill reference in $cust_name: $ref_path not found"
+      fi
+    done < <(grep 'source:' "$cust_file" || true)
+  done
+
   # Summary
   echo ""
   if [[ -d "$backup_dir" ]]; then
@@ -828,6 +889,11 @@ cmd_validate() {
     [[ -d "$TARGET/docs/$dir" ]]; check "Docs: $dir" $?
   done
 
+  # Custom directories (ADR-020: user-owned write targets, ADR-026: stakeholder agents)
+  [[ -d "$TARGET/custom/skills" ]]; check "custom/skills/ exists" $?
+  [[ -d "$TARGET/custom/templates" ]]; check "custom/templates/ exists" $?
+  [[ -d "$TARGET/custom/stakeholders" ]]; check "custom/stakeholders/ exists" $?
+
   # Version
   local version
   version="$(extract_yaml_value "$TARGET/_gaia/_config/global.yaml" "framework_version")"
@@ -930,6 +996,7 @@ ${BOLD}Commands:${RESET}
 
 ${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
@@ -1003,6 +1070,14 @@ parse_args() {
         OPT_VERBOSE=true
         shift
         ;;
+      --branch)
+        if [[ -z "${2:-}" ]]; then
+          error "--branch requires a branch name argument"
+          exit 1
+        fi
+        OPT_BRANCH="$2"
+        shift 2
+        ;;
       --help|-h)
         usage
         exit 0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-framework",
-  "version": "1.65.1",
+  "version": "1.83.2",
   "description": "GAIA — Generative Agile Intelligence Architecture installer",
   "bin": {
     "gaia-framework": "./bin/gaia-framework.js"

package/_gaia/_memory/tier2-results/checkpoint-resume-2026-03-24.yaml

@@ -1,6 +0,0 @@
-test_name: "checkpoint-resume-reliability"
-date: "2026-03-24"
-result: "pass"
-observations: "All 10 test scenarios passed. Checkpoint validation (schema, checksums, legacy format), resume state reconstruction (happy path, error cases), and file modification detection (modified, deleted) all verified. 45 total tests: 31 unit + 14 Tier 2."
-runner: "Cleo (typescript-dev)"
-framework_version: "1.48.3"

package/_gaia/_memory/tier2-results/engine-scenarios-2026-03-22.yaml

@@ -1,14 +0,0 @@
-test_name: engine-scenarios
-date: "2026-03-22T00:00:00Z"
-result: pass
-observations: |
-  All 6 ACs validated via 18 structural tests:
-  - AC1: Step ordering verified in workflow.xml and dev-story instructions.xml (4 tests)
-  - AC2: Checkpoint YAML schema validated with all required fields (3 tests)
-  - AC3: Quality gate structure validated across all workflow configs (3 tests)
-  - AC4: Variable resolution verified — all vars in known set, engine requires global.yaml (3 tests)
-  - AC5: Execution mode switching definitions validated in workflow.xml (3 tests)
-  - AC6: tier2-results directory exists, result YAML schema validated (2 tests)
-  Zero regressions in existing Tier 1 tests (3486 passing).
-runner: vitest
-framework_version: "1.45.0"