gaia-framework 1.87.0 → 1.105.0

package/.claude/commands/gaia-ci-edit.md

@@ -0,0 +1,17 @@
+---
+name: 'ci-edit'
+description: 'Edit the ci_cd.promotion_chain in global.yaml — add, remove, edit, or reorder environments.'
+model: sonnet
+---
+
+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/ci-edit/workflow.yaml as 'workflow-config'
+4. Follow workflow.xml instructions EXACTLY
+5. Save outputs after EACH section
+</steps>
+
+$ARGUMENTS

package/CLAUDE.md

@@ -254,6 +254,16 @@ Publishing is fully automated — no manual steps required beyond creating the p
 
 After a release, verify: `npm view gaia-framework version`
 
+## Sprint Gate (Upgrade Protection)
+
+The installer's `update` command includes a sprint gate that prevents framework upgrades while a sprint is active. Before any files are modified, the installer reads `docs/implementation-artifacts/sprint-status.yaml` and checks whether any story has status `in-progress`, `review`, or `ready-for-dev`.
+
+- **Active sprint detected:** the upgrade halts with exit code 1 and a message identifying the sprint and the number of active stories.
+- **No active sprint** (all stories `done` or `backlog`): the gate passes and the upgrade proceeds.
+- **No sprint file:** the gate passes silently (fresh project or no sprint started).
+
+To bypass the gate (not recommended): `gaia-install.sh update --skip-sprint-gate [target]`
+
 ## Do Not
 
 - Pre-load files — load at runtime when needed

package/_gaia/_config/environment-presets.yaml

@@ -0,0 +1,140 @@
+# GAIA Environment Presets — E20-S2 (FR-245, ADR-033)
+#
+# User-facing entry point for promotion-chain configuration. Each preset is a
+# complete, ready-to-use promotion_chain array that can be copied into
+# global.yaml under `ci_cd.promotion_chain`. The presets are consumed by
+# /gaia-ci-setup (E20-S3) which offers them during initial project setup.
+#
+# The schema of each promotion_chain entry is defined in architecture §10.24.1
+# and enforced by the E20-S1 validator (test/validators/promotion-chain-validator.js).
+# Required fields per entry: id, name, branch, ci_provider.
+# Optional fields used here: merge_strategy, environment, test_tiers, auto_merge,
+# approval_required, description, ci_checks.
+#
+# Test-tier convention (§10.24.3): additive — later environments include all
+# earlier tiers plus additional ones (e.g., [1] -> [1, 2] -> [1, 2, 3]).
+#
+# Backward compatibility (NFR-045): this file is purely additive. Projects that
+# do not set `ci_cd.promotion_chain` in global.yaml are unaffected.
+
+# ─────────────────────────────────────────────────────────────────────────────
+# solo — Solo developer shipping direct to main
+# ─────────────────────────────────────────────────────────────────────────────
+solo:
+  description: "Solo developer shipping direct to main. Single environment, auto-merge, full test coverage on the only branch."
+  promotion_chain:
+    - id: "prod"
+      name: "Production"
+      branch: "main"
+      environment: "production"
+      ci_provider: "github_actions"
+      merge_strategy: "squash"
+      test_tiers: [1, 2, 3]
+      auto_merge: true
+      description: "Solo preset — single environment on main. auto_merge is enabled because there is no upstream environment to promote from."
+
+# ─────────────────────────────────────────────────────────────────────────────
+# small-team — 2-5 developers with a single pre-prod gate
+# ─────────────────────────────────────────────────────────────────────────────
+small-team:
+  description: "Small team (2-5 developers) with a single pre-prod gate. Feature branches merge to develop for integration, then promote to main for release."
+  promotion_chain:
+    - id: "dev"
+      name: "Development"
+      branch: "develop"
+      environment: "development"
+      ci_provider: "github_actions"
+      merge_strategy: "squash"
+      test_tiers: [1]
+      auto_merge: false
+      description: "Integration branch for the small team. Runs tier-1 (unit + lint) on every feature merge."
+    - id: "prod"
+      name: "Production"
+      branch: "main"
+      environment: "production"
+      ci_provider: "github_actions"
+      merge_strategy: "squash"
+      test_tiers: [1, 2, 3]
+      auto_merge: false
+      description: "Release branch. Runs the full tier-1/2/3 suite before promotion from develop."
+
+# ─────────────────────────────────────────────────────────────────────────────
+# standard — Standard three-tier flow (dev -> staging -> prod)
+# ─────────────────────────────────────────────────────────────────────────────
+standard:
+  description: "Standard three-tier flow for most product teams. Feature branches land on develop, promote to staging for pre-prod validation, then promote to main for release."
+  promotion_chain:
+    - id: "dev"
+      name: "Development"
+      branch: "develop"
+      environment: "development"
+      ci_provider: "github_actions"
+      merge_strategy: "squash"
+      test_tiers: [1]
+      auto_merge: false
+      description: "Integration branch. Tier-1 tests run on every feature merge."
+    - id: "staging"
+      name: "Staging"
+      branch: "staging"
+      environment: "staging"
+      ci_provider: "github_actions"
+      merge_strategy: "squash"
+      test_tiers: [1, 2]
+      auto_merge: false
+      description: "Pre-production validation. Adds tier-2 (integration) tests on top of tier-1."
+    - id: "prod"
+      name: "Production"
+      branch: "main"
+      environment: "production"
+      ci_provider: "github_actions"
+      merge_strategy: "squash"
+      test_tiers: [1, 2, 3]
+      auto_merge: false
+      description: "Production release. Runs the full tier-1/2/3 suite before promotion from staging."
+
+# ─────────────────────────────────────────────────────────────────────────────
+# enterprise — Four-stage flow with dedicated UAT and approval gates
+# ─────────────────────────────────────────────────────────────────────────────
+enterprise:
+  description: "Enterprise four-stage flow with a dedicated UAT environment and mandatory approval gates on staging and production. Uses merge (not squash) to preserve individual commit history for audit trails."
+  promotion_chain:
+    - id: "dev"
+      name: "Development"
+      branch: "develop"
+      environment: "development"
+      ci_provider: "github_actions"
+      merge_strategy: "merge"
+      test_tiers: [1]
+      auto_merge: false
+      approval_required: false
+      description: "Integration branch. Tier-1 tests (unit + lint) on every feature merge."
+    - id: "uat"
+      name: "User Acceptance Testing"
+      branch: "uat"
+      environment: "uat"
+      ci_provider: "github_actions"
+      merge_strategy: "merge"
+      test_tiers: [1, 2]
+      auto_merge: false
+      approval_required: false
+      description: "User acceptance testing environment. Adds tier-2 integration tests. Business stakeholders validate features here before staging promotion."
+    - id: "staging"
+      name: "Staging"
+      branch: "staging"
+      environment: "staging"
+      ci_provider: "github_actions"
+      merge_strategy: "merge"
+      test_tiers: [1, 2, 3]
+      auto_merge: false
+      approval_required: true
+      description: "Pre-production staging. Runs the full tier-1/2/3 suite. Requires explicit approval before promotion — enforced by branch protection."
+    - id: "prod"
+      name: "Production"
+      branch: "main"
+      environment: "production"
+      ci_provider: "github_actions"
+      merge_strategy: "merge"
+      test_tiers: [1, 2, 3]
+      auto_merge: false
+      approval_required: true
+      description: "Production release. Requires explicit approval before promotion from staging — enforced by branch protection and a release manager sign-off."

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.87.0"
+framework_version: "1.105.0"
 
 # User settings
 user_name: "jlouage"

package/_gaia/_config/lifecycle-sequence.yaml

@@ -531,6 +531,15 @@ sequence:
     next:
       primary: /gaia-readiness-check
 
+  ci-edit:
+    module: testing
+    command: /gaia-ci-edit
+    next:
+      standalone: true
+      suggestions:
+        - command: /gaia-build-configs
+          context: "Regenerate resolved configs after editing the promotion chain"
+
   atdd:
     module: testing
     command: /gaia-atdd

package/_gaia/_config/workflow-manifest.csv

@@ -40,6 +40,7 @@ name,displayName,description,module,phase,path,command,agent
 "test-design","Test Design","Create risk-based test plans","testing","anytime","_gaia/testing/workflows/test-design/workflow.yaml","gaia-test-design","test-architect"
 "test-framework","Test Framework","Initialize test framework","testing","anytime","_gaia/testing/workflows/test-framework/workflow.yaml","gaia-test-framework","test-architect"
 "ci-setup","CI Setup","Scaffold CI/CD quality pipeline","testing","anytime","_gaia/testing/workflows/ci-setup/workflow.yaml","gaia-ci-setup","test-architect"
+"ci-edit","CI Edit","Edit ci_cd.promotion_chain in global.yaml (add/remove/edit/reorder environments)","testing","anytime","_gaia/testing/workflows/ci-edit/workflow.yaml","gaia-ci-edit","test-architect"
 "atdd","ATDD","Generate failing acceptance tests","testing","anytime","_gaia/testing/workflows/atdd/workflow.yaml","gaia-atdd","test-architect"
 "test-automation","Test Automation","Expand automated test coverage","testing","anytime","_gaia/testing/workflows/test-automation/workflow.yaml","gaia-test-automate","test-architect"
 "test-review","Test Review","Review test quality","testing","anytime","_gaia/testing/workflows/test-review/workflow.yaml","gaia-test-review","test-architect"

package/_gaia/core/engine/workflow.xml

@@ -51,6 +51,8 @@ execution modes (normal/yolo/planning), checkpoints, and quality gates.
     <action>Resolve {date} to current date</action>
     <action>Ask user for any remaining unresolved variables</action>
 
+    <!-- ci_cd backward-compat tolerance (E20-S11 / NFR-045 / ADR-033) — Config resolution treats a missing or empty ci_cd block as a no-op: no defaults are injected, no warning is emitted, and downstream workflows that depend on ci_cd.promotion_chain MUST consult the canonical chainPresent() predicate in scripts/lib/promotion-chain-guard.js rather than re-implementing the absent-variant check. -->
+
     <!-- Template Resolution (ADR-020, FR-101) — custom/templates/ overrides _gaia/lifecycle/templates/ -->
     <!-- Resolution order for template reads: custom/templates/{filename} > _gaia/lifecycle/templates/{filename} -->
     <!-- Resolution order for template writes: custom/templates/ ONLY — NEVER _gaia/lifecycle/templates/ -->

package/_gaia/core/validators/ci-edit-audit.js

@@ -0,0 +1,181 @@
+/**
+ * /gaia-ci-edit Audit Trail (E20-S13 AC5)
+ *
+ * Writes an audit checkpoint every time a user adds, removes, reorders, or
+ * modifies an entry in `ci_cd.promotion_chain`. The checkpoint format
+ * follows the existing `_memory/checkpoints/` YAML conventions so
+ * `/gaia-resume` and future audit tooling can discover and replay the
+ * history deterministically.
+ *
+ * Checkpoint schema:
+ *   user: <string>
+ *   timestamp: <ISO 8601 UTC>
+ *   operation: add|remove|reorder|modify
+ *   before_state: <full promotion_chain array before the edit>
+ *   after_state:  <full promotion_chain array after  the edit>
+ *   diff_summary: <human-readable change list: added/removed/modified/reordered>
+ *
+ * Design principles:
+ *   - Deterministic filenames: `ci-edit-<iso-8601>.yaml` with colons
+ *     replaced by hyphens so the name is filesystem-safe on every OS.
+ *   - No external YAML dependency — the checkpoint writer emits a small,
+ *     strict YAML subset. Round-tripping through a real YAML parser is
+ *     covered in the ci-edit test suite; this module stays dependency-free.
+ *   - Pure function at the edges: the filesystem write is the only side
+ *     effect, and the caller provides `checkpointDir` and `now`.
+ *
+ * @module ci-edit-audit
+ */
+
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Build the filesystem-safe ISO-8601 timestamp component.
+ * @param {Date} date
+ * @returns {string} e.g., "2026-04-08T09-15-30Z"
+ */
+function buildTimestampSlug(date) {
+  return date.toISOString().replace(/:/g, "-").replace(/\.\d{3}Z$/, "Z");
+}
+
+/**
+ * Compute a human-readable diff summary between two promotion_chain arrays.
+ *
+ * - Entries present only in `after` → added
+ * - Entries present only in `before` → removed
+ * - Entries present in both with mutated contents → modified
+ * - Entries present in both identical but in different positions → reordered
+ *
+ * @param {Array<object>} before
+ * @param {Array<object>} after
+ * @returns {{added:string[], removed:string[], modified:string[], reordered:boolean}}
+ */
+export function computeDiffSummary(before, after) {
+  const beforeList = Array.isArray(before) ? before : [];
+  const afterList = Array.isArray(after) ? after : [];
+  const beforeById = new Map(beforeList.map((e) => [e?.id, e]));
+  const afterById = new Map(afterList.map((e) => [e?.id, e]));
+
+  const added = [];
+  const removed = [];
+  const modified = [];
+
+  for (const [id, afterEntry] of afterById.entries()) {
+    if (!beforeById.has(id)) {
+      added.push(id);
+      continue;
+    }
+    const beforeEntry = beforeById.get(id);
+    if (JSON.stringify(beforeEntry) !== JSON.stringify(afterEntry)) {
+      modified.push(id);
+    }
+  }
+  for (const id of beforeById.keys()) {
+    if (!afterById.has(id)) removed.push(id);
+  }
+
+  // Reorder detection: same set of ids, different ordering, no content changes.
+  let reordered = false;
+  if (added.length === 0 && removed.length === 0 && modified.length === 0) {
+    const beforeOrder = beforeList.map((e) => e?.id).join("|");
+    const afterOrder = afterList.map((e) => e?.id).join("|");
+    if (beforeOrder !== afterOrder) reordered = true;
+  }
+
+  return { added, removed, modified, reordered };
+}
+
+/**
+ * Minimal YAML emitter for the audit checkpoint. Handles strings, numbers,
+ * booleans, arrays, and nested objects — enough for promotion_chain entries.
+ *
+ * @param {*} value
+ * @param {number} indent
+ * @returns {string}
+ */
+function emitYaml(value, indent = 0) {
+  const pad = "  ".repeat(indent);
+  if (value === null || value === undefined) return "null";
+  if (typeof value === "string") {
+    // Quote if the string contains YAML-significant characters.
+    if (/[:#\-?\[\]{}&*!|>'"%@`,\n]/.test(value) || value === "") {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) {
+    if (value.length === 0) return "[]";
+    return value
+      .map((item) => {
+        if (item && typeof item === "object" && !Array.isArray(item)) {
+          const inner = emitYaml(item, indent + 1)
+            .split("\n")
+            .map((line, idx) => (idx === 0 ? line : `${pad}  ${line}`))
+            .join("\n");
+          return `${pad}- ${inner}`;
+        }
+        return `${pad}- ${emitYaml(item, indent + 1)}`;
+      })
+      .join("\n");
+  }
+  if (typeof value === "object") {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    return entries
+      .map(([k, v]) => {
+        if (v && typeof v === "object") {
+          if (Array.isArray(v) && v.length === 0) return `${pad}${k}: []`;
+          if (!Array.isArray(v) && Object.keys(v).length === 0) return `${pad}${k}: {}`;
+          const nested = emitYaml(v, indent + 1);
+          return `${pad}${k}:\n${nested}`;
+        }
+        return `${pad}${k}: ${emitYaml(v, indent + 1)}`;
+      })
+      .join("\n");
+  }
+  return JSON.stringify(value);
+}
+
+/**
+ * Write a /gaia-ci-edit audit checkpoint to disk.
+ *
+ * @param {{
+ *   operation: "add"|"remove"|"reorder"|"modify",
+ *   user: string,
+ *   beforeState: Array<object>,
+ *   afterState: Array<object>,
+ *   checkpointDir: string,
+ *   now?: Date,
+ * }} params
+ * @returns {string} Absolute path to the written checkpoint file.
+ */
+export function writeCiEditAuditCheckpoint(params) {
+  const { operation, user, beforeState, afterState, checkpointDir, now } = params || {};
+  if (!checkpointDir || typeof checkpointDir !== "string") {
+    throw new Error("writeCiEditAuditCheckpoint: checkpointDir is required");
+  }
+
+  const stamp = now instanceof Date ? now : new Date();
+  const timestamp = stamp.toISOString();
+  const slug = buildTimestampSlug(stamp);
+  const filename = `ci-edit-${slug}.yaml`;
+
+  const diffSummary = computeDiffSummary(beforeState, afterState);
+
+  const payload = {
+    workflow: "ci-edit",
+    user: user || "unknown",
+    timestamp,
+    operation,
+    before_state: beforeState || [],
+    after_state: afterState || [],
+    diff_summary: diffSummary,
+  };
+
+  mkdirSync(checkpointDir, { recursive: true });
+  const filePath = join(checkpointDir, filename);
+  writeFileSync(filePath, emitYaml(payload) + "\n", "utf8");
+  return filePath;
+}

package/_gaia/core/validators/ci-edit-test-env-scan.js

@@ -0,0 +1,89 @@
+/**
+ * ci-edit Remove Safety Scan — test-environment.yaml target (E20-S10, AC5)
+ *
+ * Scans a `test-environment.yaml` payload for tier entries that reference a
+ * given promotion chain environment id via `promotion_chain_env_id`, so the
+ * `/gaia-ci-edit` remove operation (E20-S4) can surface impacted tiers and
+ * warn the user before deleting an environment from `ci_cd.promotion_chain`.
+ *
+ * This module intentionally does NOT rely on a full YAML parser — it uses a
+ * minimal line-based scanner tuned to the manifest schema (flat runner list
+ * with scalar fields). This keeps the scan dependency-free and resilient to
+ * partial manifests.
+ *
+ * Architecture references:
+ *   - ADR-033: Multi-Environment Promotion Chain
+ *   - §10.24.4: /gaia-ci-edit cascade updates
+ *
+ * @module ci-edit-test-env-scan
+ */
+
+/**
+ * Scan a test-environment.yaml content string for tier entries that reference
+ * the given environment id.
+ *
+ * @param {string|null|undefined} content — The raw YAML content.
+ * @param {string} targetEnvId — The id being removed from the promotion chain.
+ * @returns {string[]} List of tier/runner names that reference the id. Empty
+ *   list if nothing matches, the content is empty, or the target id is falsy.
+ */
+export function scanTestEnvironmentForEnvId(content, targetEnvId) {
+  if (!content || typeof content !== "string") return [];
+  if (!targetEnvId) return [];
+
+  const lines = content.split("\n");
+  const references = [];
+  let currentRunnerName = null;
+
+  for (const rawLine of lines) {
+    // Strip trailing comments and whitespace
+    const line = rawLine.replace(/#.*$/, "").trimEnd();
+    if (line.trim() === "") continue;
+
+    const trimmed = line.trimStart();
+
+    // Detect a new runner entry: "- name: <value>"
+    const runnerNameMatch = trimmed.match(/^-\s+name:\s*(.+)$/);
+    if (runnerNameMatch) {
+      currentRunnerName = stripQuotes(runnerNameMatch[1].trim());
+      continue;
+    }
+
+    // Detect an indented "name:" line for the current runner (alternative form)
+    const altNameMatch = trimmed.match(/^name:\s*(.+)$/);
+    if (altNameMatch && !trimmed.startsWith("- ")) {
+      // Only honor if we're already inside a runner block (indent > 0)
+      const indent = line.length - line.trimStart().length;
+      if (indent > 0) {
+        currentRunnerName = stripQuotes(altNameMatch[1].trim());
+      }
+      continue;
+    }
+
+    // Detect "promotion_chain_env_id: <value>" within the current runner
+    const envIdMatch = trimmed.match(/^promotion_chain_env_id:\s*(.+)$/);
+    if (envIdMatch && currentRunnerName) {
+      const value = stripQuotes(envIdMatch[1].trim());
+      if (value === targetEnvId) {
+        references.push(currentRunnerName);
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Strip surrounding single or double quotes from a YAML scalar value.
+ * @param {string} value
+ * @returns {string}
+ */
+function stripQuotes(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}